Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

feat(api): create checklist items in bulk (#683)

I'm Groot 🌳fd5caf9e9137
diff --git a/apps/api/src/mcp/__tests__/integration/structured-results.test.ts b/apps/api/src/mcp/__tests__/integration/structured-results.test.ts
index da6c2cf3..c95af148 100644
--- a/apps/api/src/mcp/__tests__/integration/structured-results.test.ts
+++ b/apps/api/src/mcp/__tests__/integration/structured-results.test.ts
@@ -77,6 +77,44 @@ describe('MCP structured results through the SDK client', () => {
expect(deleted.structuredContent).toEqual({ ok: true, status: 204, data: null });
});
+ it('creates a checklist batch through the SDK and returns a validated array result', async () => {
+ const owner = await signUpTestUser();
+ const api = authedApi(owner.cookie);
+ await createProject(api, { key: 'MKT', name: 'Marketing' });
+ const view = await api.projects({ projectKey: 'MKT' }).get();
+ const issue = await api.projects({ projectKey: 'MKT' }).issues.post({
+ columnId: view.data!.columns[0].id,
+ title: 'Release',
+ });
+ const checklist = await api
+ .issues({ issueId: issue.data!.id })
+ .checklists.post({ title: 'Steps' });
+ const client = await connect(owner.userId);
+ const listed = await client.listTools();
+ const tool = listed.tools.find((entry) => entry.name === 'create_checklist_items');
+ expect(tool?.inputSchema.properties?.items).toMatchObject({
+ type: 'array',
+ minItems: 1,
+ maxItems: 100,
+ });
+ const items = [{ content: 'Tag release' }, { content: 'Publish notes' }];
+ const result = await callTool(client, {
+ name: 'create_checklist_items',
+ arguments: { checklistId: checklist.data!.id, items },
+ });
+ expect(result.isError).toBe(false);
+ expect(result.structuredContent).toMatchObject({ ok: true, status: 201, data: items });
+ const invalid = await callTool(client, {
+ name: 'create_checklist_items',
+ arguments: { checklistId: checklist.data!.id, items: [] },
+ });
+ expect(invalid.isError).toBe(true);
+ expect(invalid.structuredContent).toMatchObject({ ok: false, status: 400 });
+ const read = await api.issues({ issueId: issue.data!.id }).get();
+ expect(read.data!.checklists[0].items).toMatchObject(items);
+ expect(read.data!.checklists[0].items).toHaveLength(2);
+ });
+
it('validates structured validation, conflict, and permission errors without changing their text', async () => {
const owner = await signUpTestUser();
const api = authedApi(owner.cookie);
diff --git a/apps/api/src/modules/agents/core/__tests__/integration/route-tools.test.ts b/apps/api/src/modules/agents/core/__tests__/integration/route-tools.test.ts
index 86357b3f..9f4d8b7f 100644
--- a/apps/api/src/modules/agents/core/__tests__/integration/route-tools.test.ts
+++ b/apps/api/src/modules/agents/core/__tests__/integration/route-tools.test.ts
@@ -80,6 +80,7 @@ describe('internal agent route tools', () => {
// ...and an action that was not granted is absent.
expect(tools.delete_issue).toBeUndefined();
expect(tools.update_issue).toBeUndefined();
+ expect(tools.create_checklist_items).toBeUndefined();
});
it('previews project activity only for the internal agent and retains full history', async () => {
@@ -303,6 +304,50 @@ describe('internal agent route tools', () => {
expect(await run(tools, 'get_project')).toMatchObject({ columns: expect.any(Array) });
});
+ it('appends a checklist batch through the granted route tool', async () => {
+ const { asOwner } = await setup();
+ const view = await asOwner.projects({ projectKey: 'MKT' }).get();
+ const issue = await asOwner.projects({ projectKey: 'MKT' }).issues.post({
+ columnId: view.data!.columns[0].id,
+ title: 'Release',
+ });
+ const checklist = await asOwner
+ .issues({ issueId: issue.data!.id })
+ .checklists.post({ title: 'Steps' });
+ const tools = await toolsFor(asOwner, ['create_checklist_items']);
+ const items = [{ content: 'Tag release' }, { content: 'Publish notes' }];
+ expect(
+ await run(tools, 'create_checklist_items', { checklistId: checklist.data!.id, items }),
+ ).toMatchObject(items);
+ const read = await asOwner.issues({ issueId: issue.data!.id }).get();
+ expect(read.data!.checklists[0].items).toMatchObject(items);
+ });
+
+ it('denies a checklist batch when the agent role cannot edit work items', async () => {
+ const { asOwner } = await setup();
+ const view = await asOwner.projects({ projectKey: 'MKT' }).get();
+ const issue = await asOwner.projects({ projectKey: 'MKT' }).issues.post({
+ columnId: view.data!.columns[0].id,
+ title: 'Release',
+ });
+ const checklist = await asOwner
+ .issues({ issueId: issue.data!.id })
+ .checklists.post({ title: 'Steps' });
+ const role = await createRole(asOwner, 'MKT', {
+ name: 'Read only',
+ permissions: { work_items: { read: true, edit: false } },
+ });
+ const tools = await toolsFor(asOwner, ['create_checklist_items'], role.data!.id);
+ expect(
+ await run(tools, 'create_checklist_items', {
+ checklistId: checklist.data!.id,
+ items: [{ content: 'Forbidden' }],
+ }),
+ ).toMatchObject({ error: expect.anything() });
+ const read = await asOwner.issues({ issueId: issue.data!.id }).get();
+ expect(read.data!.checklists[0].items).toEqual([]);
+ });
+
it("enforces the agent's role: a forbidden action returns the route's error", async () => {
const { asOwner } = await setup();
const view = await asOwner.projects({ projectKey: 'MKT' }).get();
@@ -406,7 +451,10 @@ describe('internal agent route tools are bound to the run project', () => {
});
it('refuses a checklist of an issue of another project', async () => {
- const { asOwner, tools, opsIssue } = await crossProject(['create_checklist_item']);
+ const { asOwner, tools, opsIssue } = await crossProject([
+ 'create_checklist_item',
+ 'create_checklist_items',
+ ]);
const checklist = await asOwner
.issues({ issueId: opsIssue })
.checklists.post({ title: 'Steps' });
@@ -414,6 +462,14 @@ describe('internal agent route tools are bound to the run project', () => {
expect(
await run(tools, 'create_checklist_item', { checklistId: checklist.data!.id, content: 'x' }),
).toEqual(outside);
+ expect(
+ await run(tools, 'create_checklist_items', {
+ checklistId: checklist.data!.id,
+ items: [{ content: 'Forbidden' }],
+ }),
+ ).toEqual(outside);
+ const read = await asOwner.issues({ issueId: opsIssue }).get();
+ expect(read.data!.checklists[0].items).toEqual([]);
});
it('refuses a cycle and an initiative of another project', async () => {
diff --git a/apps/api/src/modules/agents/core/runtime/tools/catalog.ts b/apps/api/src/modules/agents/core/runtime/tools/catalog.ts
index 9c71729f..e4ac0708 100644
--- a/apps/api/src/modules/agents/core/runtime/tools/catalog.ts
+++ b/apps/api/src/modules/agents/core/runtime/tools/catalog.ts
@@ -138,6 +138,13 @@ export const AGENT_ACTIONS: ToolMeta[] = [
description: 'Append an item to a checklist on an issue.',
always: false,
},
+ {
+ key: 'create_checklist_items',
+ group: 'issues',
+ label: 'Add checklist items in bulk',
+ description: 'Append up to 100 items to a checklist in one operation.',
+ always: false,
+ },
{
key: 'update_checklist_item',
group: 'issues',
diff --git a/apps/api/src/modules/issues/__tests__/integration/checklists.test.ts b/apps/api/src/modules/issues/__tests__/integration/checklists.test.ts
index 8a15671b..df8780c9 100644
--- a/apps/api/src/modules/issues/__tests__/integration/checklists.test.ts
+++ b/apps/api/src/modules/issues/__tests__/integration/checklists.test.ts
@@ -38,6 +38,12 @@ function addItem(client: Api, checklistId: number, content: string) {
return client.checklists({ checklistId }).items.post({ content });
}
+function addItems(client: Api, checklistId: number, contents: string[]) {
+ return client.checklists({ checklistId }).items.batch.post({
+ items: contents.map((content) => ({ content })),
+ });
+}
+
async function read(client: Api, issueId: number) {
const res = await client.issues({ issueId }).get();
return res.data!;
@@ -299,6 +305,118 @@ describe('checklists', () => {
});
});
+ describe('batch items', () => {
+ it('appends in input order and records each item without changing existing items', async () => {
+ const { asOwner, columnId } = await setupProject();
+ const { issue, checklist } = await issueWithChecklist(asOwner, columnId);
+ const previous = (await addItem(asOwner, checklist.id, 'Already done')).data!;
+ await asOwner.checklists.items({ itemId: previous.id }).patch({ done: true });
+
+ const result = await addItems(asOwner, checklist.id, ['Tag release', 'Publish notes']);
+ expect(result.status).toBe(201);
+ expect(result.data).toMatchObject([
+ { content: 'Tag release', done: false, position: previous.position + 1000 },
+ { content: 'Publish notes', done: false, position: previous.position + 2000 },
+ ]);
+ expect((await read(asOwner, issue.id)).checklists[0].items).toEqual([
+ { ...previous, done: true },
+ ...result.data!,
+ ]);
+ const feed = await asOwner.issues({ issueId: issue.id }).feed.get({ query: {} });
+ for (const item of result.data!) {
+ expect(feed.data!.items).toContainEqual(
+ expect.objectContaining({
+ action: 'checklist_item_add',
+ payload: {
+ subject: { value: checklist.title, id: checklist.id },
+ to: { value: item.content, id: item.id },
+ },
+ }),
+ );
+ }
+ });
+
+ it('accepts 100 items and 500-character content, and still supports single-item appends', async () => {
+ const { asOwner, columnId } = await setupProject();
+ const { issue, checklist } = await issueWithChecklist(asOwner, columnId);
+ const contents = Array.from({ length: 100 }, (_, i) =>
+ i === 0 ? 'x'.repeat(500) : `Item ${i}`,
+ );
+ const result = await addItems(asOwner, checklist.id, contents);
+ expect(result.status).toBe(201);
+ expect(result.data!.map((item) => item.content)).toEqual(contents);
+ const last = await addItem(asOwner, checklist.id, 'Last');
+ expect(last.status).toBe(201);
+ expect(last.data!.position).toBe(result.data![99].position + 1000);
+ expect((await read(asOwner, issue.id)).checklists[0].items).toHaveLength(101);
+ });
+
+ it.each([0, 101])('rejects a batch of %i items without writing any', async (size) => {
+ const { asOwner, columnId } = await setupProject();
+ const { issue, checklist } = await issueWithChecklist(asOwner, columnId);
+ const before = await feedActions(asOwner, issue.id);
+ const result = await addItems(asOwner, checklist.id, Array(size).fill('Step'));
+ expect(result.status).toBe(400);
+ expect((await read(asOwner, issue.id)).checklists[0].items).toEqual([]);
+ expect(await feedActions(asOwner, issue.id)).toEqual(before);
+ });
+
+ it.each(['', 'x'.repeat(501)])(
+ 'rejects invalid content without a partial batch',
+ async (invalid) => {
+ const { asOwner, columnId } = await setupProject();
+ const { issue, checklist } = await issueWithChecklist(asOwner, columnId);
+ const before = await feedActions(asOwner, issue.id);
+ expect((await addItems(asOwner, checklist.id, ['Valid', invalid])).status).toBe(400);
+ expect((await read(asOwner, issue.id)).checklists[0].items).toEqual([]);
+ expect(await feedActions(asOwner, issue.id)).toEqual(before);
+ },
+ );
+
+ it('returns 404 for an unknown checklist', async () => {
+ const { asOwner, columnId } = await setupProject();
+ const { checklist } = await issueWithChecklist(asOwner, columnId);
+ expect((await addItems(asOwner, checklist.id + 999, ['Step'])).status).toBe(404);
+ });
+
+ it('denies a non-member without changing the checklist', async () => {
+ const { asOwner, columnId } = await setupProject();
+ const { issue, checklist } = await issueWithChecklist(asOwner, columnId);
+ const outsider = await signUpTestUser();
+ const result = await addItems(authedApi(outsider.cookie), checklist.id, ['Forbidden']);
+ expect(result.status).toBe(403);
+ expect((await read(asOwner, issue.id)).checklists[0].items).toEqual([]);
+ });
+
+ it('respects the project checklist switch', async () => {
+ const { asOwner, columnId } = await setupProject();
+ const { issue, checklist } = await issueWithChecklist(asOwner, columnId);
+ const settings = await asOwner.projects({ projectKey: 'MKT' }).settings.patch({
+ features: { checklists: false },
+ });
+ expect(settings.status).toBe(200);
+ expect((await addItems(asOwner, checklist.id, ['Forbidden'])).status).toBe(403);
+ expect((await read(asOwner, issue.id)).checklists[0].items).toEqual([]);
+ });
+
+ it('keeps concurrent batches and a single append in separate ordered ranges', async () => {
+ const { asOwner, columnId } = await setupProject();
+ const { issue, checklist } = await issueWithChecklist(asOwner, columnId);
+ const [first, second, single] = await Promise.all([
+ addItems(asOwner, checklist.id, ['A1', 'A2']),
+ addItems(asOwner, checklist.id, ['B1', 'B2']),
+ addItem(asOwner, checklist.id, 'Single'),
+ ]);
+ expect([first.status, second.status, single.status]).toEqual([201, 201, 201]);
+ const groups = [first.data!, second.data!, [single.data!]].sort(
+ (a, b) => a[0].position - b[0].position,
+ );
+ const items = (await read(asOwner, issue.id)).checklists[0].items;
+ expect(items.map((item) => item.id)).toEqual(groups.flat().map((item) => item.id));
+ expect(new Set(items.map((item) => item.position)).size).toBe(5);
+ });
+ });
+
// Structural changes belong in the feed; a checkbox toggle is the most frequent
// write here and would bury the rest of it.
describe('activity', () => {
diff --git a/apps/api/src/modules/issues/checklists.ts b/apps/api/src/modules/issues/checklists.ts
index 49e57975..11ffd47c 100644
--- a/apps/api/src/modules/issues/checklists.ts
+++ b/apps/api/src/modules/issues/checklists.ts
@@ -1,7 +1,7 @@
import { db, issueChecklist, issueChecklistItem } from '@repo/db';
import { and, asc, eq, inArray, sql } from 'drizzle-orm';
import { HttpError } from '#shared/lib';
-import { recordActivity, rowSide } from './activity';
+import { recordActivity, recordActivityEntries, rowSide } from './activity';
// Checklists on an issue: a list of steps too small to be subtasks of their own.
// An issue holds several checklists, each holding its items; both are ordered by
@@ -210,30 +210,56 @@ export async function createChecklistItem(
content: string,
actorUserId?: string | null,
): Promise<ChecklistItemRow> {
- const checklist = await checklistContext(checklistId);
- const [row] = await db
- .insert(issueChecklistItem)
- .values({
- checklistId,
- content,
- position: sql<number>`(select coalesce(max(${issueChecklistItem.position}), 0) + 1000 from ${issueChecklistItem} where ${eq(issueChecklistItem.checklistId, checklistId)})`,
- })
- .returning(itemColumns);
-
- await recordActivity(
- checklist.issueId,
- [
- {
- action: 'checklist_item_add',
- subject: rowSide(checklist.title, checklistId),
- to: rowSide(content, row.id),
- },
- ],
- actorUserId,
- );
+ const [row] = await createChecklistItems(checklistId, [{ content }], actorUserId);
return row;
}
+export async function createChecklistItems(
+ checklistId: number,
+ items: { content: string }[],
+ actorUserId?: string | null,
+): Promise<ChecklistItemRow[]> {
+ return db.transaction(async (tx) => {
+ // Serialize appends so concurrent batches occupy separate ordered ranges.
+ const [checklist] = await tx
+ .select({ issueId: issueChecklist.issueId, title: issueChecklist.title })
+ .from(issueChecklist)
+ .where(eq(issueChecklist.id, checklistId))
+ .for('update');
+ if (!checklist) throw new HttpError(404, 'Checklist not found');
+
+ const [last] = await tx
+ .select({ position: sql<number>`coalesce(max(${issueChecklistItem.position}), 0)` })
+ .from(issueChecklistItem)
+ .where(eq(issueChecklistItem.checklistId, checklistId));
+ const rows = await tx
+ .insert(issueChecklistItem)
+ .values(
+ items.map(({ content }, index) => ({
+ checklistId,
+ content,
+ position: last.position + (index + 1) * 1000,
+ })),
+ )
+ .returning(itemColumns);
+
+ rows.sort((a, b) => a.position - b.position);
+ await recordActivityEntries(
+ rows.map((row) => ({
+ issueId: checklist.issueId,
+ event: {
+ action: 'checklist_item_add',
+ subject: rowSide(checklist.title, checklistId),
+ to: rowSide(row.content, row.id),
+ },
+ })),
+ actorUserId,
+ tx,
+ );
+ return rows;
+ });
+}
+
export async function updateChecklistItem(
itemId: number,
patch: { content?: string; done?: boolean },
diff --git a/apps/api/src/modules/issues/index.ts b/apps/api/src/modules/issues/index.ts
index 3a688f13..5282466c 100644
--- a/apps/api/src/modules/issues/index.ts
+++ b/apps/api/src/modules/issues/index.ts
@@ -81,6 +81,7 @@ import { DevelopmentLinkResponse } from '#modules/git/model';
import {
createChecklist,
createChecklistItem,
+ createChecklistItems,
deleteChecklist,
deleteChecklistItem,
getChecklistIssueId,
@@ -146,6 +147,7 @@ import {
issueLinkParams,
checklistTitleBody,
createChecklistItemBody,
+ createChecklistItemsBody,
updateChecklistItemBody,
feedRangeQuery,
createCommentBody,
@@ -1077,6 +1079,26 @@ export const issueRoutes = new Elysia({ name: 'issues', detail: { tags: ['Issues
},
)
+ .post(
+ '/checklists/:checklistId/items/batch',
+ async ({ params, body, user, set }) => {
+ set.status = 201;
+ return createChecklistItems(params.checklistId, body.items, requireUser(user).id);
+ },
+ {
+ body: createChecklistItemsBody,
+ params: checklistParams,
+ checklist: 'edit',
+ response: { 201: t.Array(ChecklistItemResponse), ...commonErrors },
+ detail: {
+ summary: 'Add checklist items in bulk',
+ description:
+ 'Append 1–100 items to an existing checklist in input order. Each content is 1–500 characters. The items and their activity entries are saved atomically.',
+ ...mcpTool('create_checklist_items'),
+ },
+ },
+ )
+
.put(
'/checklists/:checklistId/items/reorder',
async ({ params, body }) => reorderChecklistItems(params.checklistId, body.orderedIds),
diff --git a/apps/api/src/modules/issues/model.ts b/apps/api/src/modules/issues/model.ts
index 0099276f..843d40de 100644
--- a/apps/api/src/modules/issues/model.ts
+++ b/apps/api/src/modules/issues/model.ts
@@ -652,6 +652,10 @@ export const checklistTitleBody = t.Object({ title: ChecklistTitleSchema });
export const createChecklistItemBody = t.Object({ content: ChecklistItemContentSchema });
+export const createChecklistItemsBody = t.Object({
+ items: t.Array(createChecklistItemBody, { minItems: 1, maxItems: 100 }),
+});
+
export const updateChecklistItemBody = t.Object({
content: t.Optional(ChecklistItemContentSchema),
done: t.Optional(t.Boolean({ description: 'Whether the item is checked off.' })),