kanbango 3.1.0 → 3.3.0

package/mcp-server.js

@@ -76,6 +76,101 @@ function invalidRequest(message, hint, details) {
   return kanban.createKanbanError('VALIDATION_ERROR', message, hint, details, false, 400);
 }
 
+const MANAGE_ACTIONS = [
+  'create',
+  'move',
+  'update',
+  'delete',
+  'epic_create',
+  'epic_update',
+  'epic_archive',
+  'epic_unarchive',
+  'epic_delete',
+  'plan_create',
+  'plan_advance',
+  'plan_evidence',
+  'plan_done',
+  'plan_status',
+  'comment_add'
+];
+
+const GUI_ACTIONS = ['start', 'stop', 'status'];
+
+const ACTION_EXAMPLES = {
+  kanban_manage: '{"action":"create","title":"Ship image","col":"planned"}',
+  kanban_gui: '{"action":"status"}'
+};
+
+function receivedKeys(args) {
+  return Object.keys(args && typeof args === 'object' ? args : {});
+}
+
+function actionRecipeMessage(toolName, allowed, opts = {}) {
+  const keys = opts.received_keys || [];
+  const example = ACTION_EXAMPLES[toolName] || `{"action":"${allowed[0]}"}`;
+  const lines = [];
+
+  if (opts.kind === 'unknown') {
+    lines.push(`Unknown action "${opts.action}" on ${toolName}.`);
+  } else {
+    lines.push(`Missing required top-level field "action" on ${toolName}.`);
+  }
+
+  lines.push('Pass action next to other args (not nested under params).');
+  lines.push(`Valid: ${allowed.join(', ')}.`);
+  lines.push(`Example: ${example}`);
+  lines.push(keys.length > 0 ? `You sent keys: ${keys.join(', ')}` : 'You sent keys: (none)');
+  return lines.join(' ');
+}
+
+function actionRecipeHint() {
+  return [
+    'Retry the same tool with top-level action set to one Valid value.',
+    'Common mistake: omitting action, or putting it under params (jira/gitlab style) — kanban uses top-level action.'
+  ].join(' ');
+}
+
+function requireToolAction(args, allowed, toolName) {
+  const action = args && args.action;
+  const keys = receivedKeys(args);
+  if (action === undefined || action === null || action === '') {
+    throw kanban.createKanbanError(
+      'MISSING_REQUIRED_FIELD',
+      actionRecipeMessage(toolName, allowed, {
+        kind: 'missing',
+        received_keys: keys,
+        action: action === undefined ? null : action
+      }),
+      actionRecipeHint(),
+      {
+        field: 'action',
+        tool: toolName,
+        received_keys: keys,
+        allowed_actions: allowed,
+        action: action === undefined ? null : action
+      },
+      false,
+      400
+    );
+  }
+  return action;
+}
+
+function unknownToolAction(action, args, allowed, toolName) {
+  const keys = receivedKeys(args);
+  return invalidRequest(
+    actionRecipeMessage(toolName, allowed, { kind: 'unknown', action, received_keys: keys }),
+    actionRecipeHint(),
+    {
+      field: 'action',
+      tool: toolName,
+      action,
+      received_keys: keys,
+      allowed_actions: allowed
+    }
+  );
+}
+
 function serializeResult(result) {
   if (typeof result === 'string') return result;
 
@@ -146,30 +241,42 @@ function formatTaskResult(task, returnShape) {
   return kanban.shapeTask(task, { view: returnShape === 'full' ? 'full' : 'summary' });
 }
 
+function guiIdentity(extra = {}) {
+  const cwd = extra.cwd || process.cwd();
+  return {
+    ...extra,
+    cwd,
+    project: extra.project || guiRegistry.projectLabel(cwd)
+  };
+}
+
 async function startGuiServer(port) {
   if (port !== undefined && port !== null && port !== '' && !normalizePort(port)) {
     throw invalidRequest('Invalid port', 'Use an integer between 1 and 65535', { port });
   }
 
   if (ownsGuiProcess() && guiPort) {
-    return {
+    return guiIdentity({
       status: 'already_running',
       owned: true,
       port: guiPort,
       pid: guiProcess.pid,
       url: `http://localhost:${guiPort}`
-    };
+    });
   }
 
   const existing = await guiRegistry.discoverRunningGui();
   if (existing) {
-    return {
+    return guiIdentity({
       status: 'already_running',
       owned: false,
       port: existing.port,
       pid: existing.pid,
-      url: existing.url
-    };
+      url: existing.url,
+      cwd: existing.cwd,
+      project: existing.project,
+      started_at: existing.started_at
+    });
   }
 
   const desiredPort = guiRegistry.resolvePreferredGuiPort(port);
@@ -194,19 +301,24 @@ async function startGuiServer(port) {
   const ready = await waitForGuiReady(childPid);
   guiPort = ready.port;
 
-  return {
+  return guiIdentity({
     status: 'started',
     owned: true,
     port: ready.port,
     pid: ready.pid,
-    url: ready.url
-  };
+    url: ready.url,
+    cwd: ready.cwd,
+    project: ready.project,
+    started_at: ready.started_at
+  });
 }
 
 async function stopGuiServer() {
   if (ownsGuiProcess()) {
     const port = guiPort;
     const pid = guiProcess.pid;
+    const project = guiRegistry.projectLabel();
+    const cwd = process.cwd();
     guiProcess.kill();
 
     const deadline = Date.now() + 2000;
@@ -219,7 +331,7 @@ async function stopGuiServer() {
     await guiRegistry.clearGuiPortFile({ force: true });
     guiProcess = null;
     guiPort = null;
-    return { status: 'stopping', owned: true, port, pid };
+    return { status: 'stopping', owned: true, port, pid, project, cwd };
   }
 
   guiProcess = null;
@@ -230,25 +342,28 @@ async function stopGuiServer() {
     return { status: 'not_running' };
   }
 
-  return {
+  return guiIdentity({
     status: 'external_running',
     owned: false,
     port: discovered.port,
     pid: discovered.pid,
     url: discovered.url,
+    cwd: discovered.cwd,
+    project: discovered.project,
+    started_at: discovered.started_at,
     hint: 'GUI was not started by this MCP process; stop refused. Stop it from the owning terminal or kill that PID manually.'
-  };
+  });
 }
 
 async function guiStatus() {
   if (ownsGuiProcess() && guiPort) {
-    return {
+    return guiIdentity({
       status: 'running',
       owned: true,
       port: guiPort,
       pid: guiProcess.pid,
       url: `http://localhost:${guiPort}`
-    };
+    });
   }
 
   guiProcess = null;
@@ -259,15 +374,16 @@ async function guiStatus() {
     return { status: 'not_running' };
   }
 
-  return {
+  return guiIdentity({
     status: 'external_running',
     owned: false,
     port: discovered.port,
     pid: discovered.pid,
     url: discovered.url,
     cwd: discovered.cwd,
+    project: discovered.project,
     started_at: discovered.started_at
-  };
+  });
 }
 
 const server = new Server(
@@ -314,6 +430,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Filter list by epic id or title'
             },
+            include_archived: {
+              type: 'boolean',
+              description: 'list/list_epics: include archived epics and their tasks (default false)'
+            },
+            include_done: {
+              type: 'boolean',
+              description: 'list_epics: include status=done epics without archived (default false)'
+            },
+            status: {
+              type: 'string',
+              enum: ['empty', 'planned', 'active', 'done', 'archived'],
+              description: 'list_epics: exact status filter (overrides live-only default)'
+            },
             view: {
               type: 'string',
               enum: READ_VIEWS,
@@ -336,19 +465,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             action: {
               type: 'string',
-              enum: [
-                'create',
-                'move',
-                'update',
-                'epic_create',
-                'epic_update',
-                'plan_create',
-                'plan_advance',
-                'plan_evidence',
-                'plan_done',
-                'plan_status'
-              ],
-              description: 'create|move|update daily; epic_create|epic_update for containers; plan_* for multi-step work'
+              enum: MANAGE_ACTIONS,
+              description: 'create|move|update|delete daily; epic_*; plan_*; comment_add'
             },
             title: {
               type: 'string',
@@ -367,7 +485,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             epic_id: {
               type: 'string',
-              description: 'Required for epic_update; optional filter/link id'
+              description: 'Required for epic_update|epic_archive|epic_unarchive|epic_delete; optional link id'
             },
             description: {
               type: 'string',
@@ -418,9 +536,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Freeform notes'
             },
+            text: {
+              type: 'string',
+              description: 'Required for comment_add. Non-empty comment body.'
+            },
+            author: {
+              type: 'string',
+              description: 'Optional comment author (default user). e.g. kocur-reviewer, worker'
+            },
             task_id: {
               type: 'string',
-              description: "Required for move/update/plan_* except plan_create. '014' or '14'."
+              description: "Required for move/update/delete/comment_add/plan_* except plan_create. '014' or '14'."
             },
             column: {
               type: 'string',
@@ -434,7 +560,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             return: {
               type: 'string',
               enum: ['none', 'summary', 'full'],
-              description: 'move/update/epic_update response size. Prefer none. Default summary. create/epic_create return full once.'
+              description: 'move/update/delete/epic_* response size. Prefer none. Default summary. create/epic_create return full once.'
             },
             index: {
               type: 'integer',
@@ -482,7 +608,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             action: {
               type: 'string',
-              enum: ['start', 'stop', 'status'],
+              enum: GUI_ACTIONS,
               description: 'start | stop (owned only) | status'
             },
             port: {
@@ -517,13 +643,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
         if (operation === 'list') {
           await kanban.migrateEpicGroups();
+          const epics = await kanban.listEpicEntities();
           let tasks = await kanban.allTasks();
           if (args.col) {
             tasks = tasks.filter((task) => task.column === args.col);
           }
+          // Explicit epic filter bypasses live-only hide (agent asked for that initiative)
           if (args.epic || args.epic_id) {
             const filter = args.epic_id || args.epic;
             tasks = tasks.filter((task) => kanban.taskMatchesEpicFilter(task, filter));
+          } else {
+            tasks = kanban.filterTasksForList(tasks, epics, {
+              include_archived: args.include_archived,
+              include_done: args.include_done
+            });
           }
 
           result = tasks.map((task) => kanban.shapeTask(task, readOptions));
@@ -544,10 +677,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const epicView = args.view === 'full' || args.view === 'planning' || args.view === 'execution'
             ? (args.view === 'execution' ? 'planning' : args.view)
             : 'summary';
-          result = epics.map((epic) => kanban.shapeEpic(epic, tasks, {
+          const shaped = epics.map((epic) => kanban.shapeEpic(epic, tasks, {
             view: Array.isArray(args.fields) && args.fields.length > 0 ? undefined : epicView,
             fields: args.fields
           }));
+          result = kanban.filterShapedEpics(shaped, {
+            include_archived: args.include_archived,
+            include_done: args.include_done,
+            status: args.status
+          });
         } else if (operation === 'show_epic') {
           const epicRef = args.epic_id || args.epic;
           if (!epicRef) {
@@ -576,7 +714,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'kanban_manage': {
-        const action = args.action;
+        const action = requireToolAction(args, MANAGE_ACTIONS, 'kanban_manage');
         const returnShape = normalizeReturnShape(args.return);
 
         switch (action) {
@@ -638,6 +776,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (args.in_scope !== undefined) epicPatch.in_scope = args.in_scope;
             if (args.out_of_scope !== undefined) epicPatch.out_of_scope = args.out_of_scope;
             if (args.notes !== undefined) epicPatch.notes = args.notes;
+            if (args.patch && args.patch.archived !== undefined) {
+              epicPatch.archived = args.patch.archived;
+            }
             const updatedEpic = await kanban.updateEpicEntity(epicId, epicPatch);
             if (returnShape === 'none') {
               result = { ok: true, epic_id: updatedEpic.id };
@@ -649,6 +790,57 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             break;
           }
 
+          case 'epic_archive':
+          case 'epic_unarchive': {
+            const epicId = args.epic_id || args.epic;
+            if (!epicId) {
+              throw invalidRequest(
+                `epic_id is required for '${action}'`,
+                'Provide an epic id like E001',
+                { action }
+              );
+            }
+            const toggled = action === 'epic_archive'
+              ? await kanban.archiveEpic(epicId)
+              : await kanban.unarchiveEpic(epicId);
+            if (returnShape === 'none') {
+              result = { ok: true, epic_id: toggled.id, archived: toggled.archived };
+            } else if (returnShape === 'summary') {
+              result = kanban.shapeEpic(toggled, await kanban.allTasks(), { view: 'summary' });
+            } else {
+              result = kanban.shapeEpic(toggled, await kanban.allTasks(), { view: 'full' });
+            }
+            break;
+          }
+
+          case 'epic_delete': {
+            const epicId = args.epic_id || args.epic;
+            if (!epicId) {
+              throw invalidRequest(
+                "epic_id is required for 'epic_delete'",
+                'Provide an epic id like E001',
+                { action }
+              );
+            }
+            result = await kanban.deleteEpic(epicId);
+            break;
+          }
+
+          case 'delete': {
+            if (!args.task_id) {
+              throw invalidRequest(
+                "task_id is required for 'delete'",
+                'Provide a task ID',
+                { action }
+              );
+            }
+            const deleted = await kanban.deleteTask(args.task_id);
+            result = returnShape === 'none'
+              ? { ok: true, task_id: deleted.task_id }
+              : deleted;
+            break;
+          }
+
           case 'move': {
             if (!args.task_id) {
               throw invalidRequest(
@@ -720,18 +912,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             result = await plan.status(args.task_id);
             break;
 
+          case 'comment_add': {
+            if (!args.task_id) {
+              throw invalidRequest(
+                "task_id is required for 'comment_add'",
+                'Provide a task ID',
+                { action }
+              );
+            }
+            if (!args.text) {
+              throw invalidRequest(
+                "text is required for 'comment_add'",
+                'Provide a non-empty comment body',
+                { action }
+              );
+            }
+            const added = await kanban.addComment(args.task_id, args.text, args.author);
+            result = returnShape === 'none'
+              ? { ok: true, comment_id: added.comment.id }
+              : returnShape === 'full'
+                ? added
+                : { ok: true, task_id: added.task_id, comment_id: added.comment.id, count: added.comments.length };
+            break;
+          }
+
           default:
-            throw invalidRequest(
-              `Unknown action: ${action}`,
-              'Use create, move, update, epic_create, epic_update, plan_create, plan_advance, plan_evidence, plan_done, or plan_status',
-              { action }
-            );
+            throw unknownToolAction(action, args, MANAGE_ACTIONS, 'kanban_manage');
         }
         break;
       }
 
       case 'kanban_gui': {
-        const action = args.action;
+        const action = requireToolAction(args, GUI_ACTIONS, 'kanban_gui');
 
         switch (action) {
           case 'start': {
@@ -747,11 +959,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             break;
           }
           default:
-            throw invalidRequest(
-              `Unknown action: ${action}`,
-              'Use one of: start, stop, status',
-              { action }
-            );
+            throw unknownToolAction(action, args, GUI_ACTIONS, 'kanban_gui');
         }
         break;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanbango",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "JSON-first local Kanban board with web GUI, CLI, and MCP server",
   "main": "index.js",
   "bin": {

package/tests/run.js

@@ -15,9 +15,12 @@ function runNode(scriptPath, args, label) {
 
 runNode(path.join('bin', 'kanban.js'), ['list', '--json'], 'CLI list');
 runNode(path.join('tests', 'update-tasks.test.js'), [], 'Update tasks test');
+runNode(path.join('tests', 'comments.test.js'), [], 'Comments test');
 runNode(path.join('tests', 'read-views.test.js'), [], 'Read views test');
 runNode(path.join('tests', 'mcp-server.test.js'), [], 'MCP server test');
 runNode(path.join('tests', 'gui-port.test.js'), [], 'GUI port test');
 runNode(path.join('tests', 'plan-workflow.test.js'), [], 'Plan workflow test');
 runNode(path.join('tests', 'agent-playbook.test.js'), [], 'Agent playbook test');
 runNode(path.join('tests', 'epics.test.js'), [], 'Epics test');
+runNode(path.join('tests', 'delete-archive.test.js'), [], 'Delete/archive test');
+runNode(path.join('tests', 'race-conditions.test.js'), [], 'Race conditions test');