kanbango 3.0.2 → 3.2.0

package/mcp-server.js

@@ -146,30 +146,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 +206,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 +236,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 +247,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 +279,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(
@@ -293,14 +314,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             operation: {
               type: 'string',
-              enum: ['list', 'show', 'help'],
-              description: 'list=scan board; show=one task (needs task_id); help=token playbook (no board I/O)',
+              enum: ['list', 'show', 'list_epics', 'show_epic', 'help'],
+              description: 'list/show=tasks; list_epics/show_epic=initiative containers; help=token playbook',
               default: 'list'
             },
             task_id: {
               type: 'string',
               description: "Required for show. Numeric id: '014' or '14'."
             },
+            epic_id: {
+              type: 'string',
+              description: "Required for show_epic. Epic id like 'E001'."
+            },
             col: {
               type: 'string',
               enum: COLS,
@@ -308,7 +333,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             epic: {
               type: 'string',
-              description: 'Filter list by epic group'
+              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',
@@ -332,12 +370,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             action: {
               type: 'string',
-              enum: ['create', 'move', 'update', 'plan_create', 'plan_advance', 'plan_evidence', 'plan_done', 'plan_status'],
-              description: 'create|move|update daily; plan_* only for accepted multi-step work with tests'
+              enum: [
+                'create',
+                'move',
+                'update',
+                'delete',
+                'epic_create',
+                'epic_update',
+                'epic_archive',
+                'epic_unarchive',
+                'epic_delete',
+                'plan_create',
+                'plan_advance',
+                'plan_evidence',
+                'plan_done',
+                'plan_status'
+              ],
+              description: 'create|move|update|delete daily; epic_create|epic_update|epic_archive|epic_unarchive|epic_delete; plan_* multi-step'
             },
             title: {
               type: 'string',
-              description: 'Required for create and plan_create'
+              description: 'Required for create, plan_create, epic_create'
             },
             col: {
               type: 'string',
@@ -348,11 +401,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             epic: {
               type: 'string',
               default: '—',
-              description: 'Epic group (create/update/plan_create)'
+              description: 'Epic id or title (create/update/plan_create). Prefer E001.'
+            },
+            epic_id: {
+              type: 'string',
+              description: 'Required for epic_update|epic_archive|epic_unarchive|epic_delete; optional link id'
             },
             description: {
               type: 'string',
-              description: 'Why/context (recommended on create)'
+              description: 'Why/context (recommended on create / epic_create)'
+            },
+            goals: {
+              type: 'string',
+              description: 'Epic outcome one-liner (recommended on epic_create)'
             },
             specs: {
               type: 'string',
@@ -397,7 +458,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             task_id: {
               type: 'string',
-              description: "Required for move/update/plan_* except plan_create. '014' or '14'."
+              description: "Required for move/update/delete/plan_* except plan_create. '014' or '14'."
             },
             column: {
               type: 'string',
@@ -411,7 +472,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             return: {
               type: 'string',
               enum: ['none', 'summary', 'full'],
-              description: 'move/update response size. Prefer none. Default summary. create always returns full task once.'
+              description: 'move/update/delete/epic_* response size. Prefer none. Default summary. create/epic_create return full once.'
             },
             index: {
               type: 'integer',
@@ -493,12 +554,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const readOptions = normalizeReadOptions(args, 'summary');
 
         if (operation === 'list') {
-          let tasks = await kanban.allEpics();
+          await kanban.migrateEpicGroups();
+          const epics = await kanban.listEpicEntities();
+          let tasks = await kanban.allTasks();
           if (args.col) {
             tasks = tasks.filter((task) => task.column === args.col);
           }
-          if (args.epic) {
-            tasks = tasks.filter((task) => task.epic_group === args.epic);
+          // 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));
@@ -512,10 +582,43 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
 
           result = kanban.shapeTask(await kanban.getTask(args.task_id), readOptions);
+        } else if (operation === 'list_epics') {
+          await kanban.migrateEpicGroups();
+          const tasks = await kanban.allTasks();
+          const epics = await kanban.listEpicEntities();
+          const epicView = args.view === 'full' || args.view === 'planning' || args.view === 'execution'
+            ? (args.view === 'execution' ? 'planning' : args.view)
+            : 'summary';
+          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) {
+            throw invalidRequest(
+              "epic_id is required for 'show_epic' operation",
+              'Provide an epic id like E001',
+              { operation }
+            );
+          }
+          await kanban.migrateEpicGroups();
+          const link = await kanban.resolveEpicRef(epicRef, { createIfMissing: false });
+          const epic = await kanban.getEpicEntity(link.epic_id);
+          const tasks = await kanban.allTasks();
+          result = kanban.shapeEpic(epic, tasks, {
+            view: args.view || 'full',
+            fields: args.fields
+          });
         } else {
           throw invalidRequest(
             `Unknown operation: ${operation}`,
-            'Use one of: list, show, help',
+            'Use one of: list, show, list_epics, show_epic, help',
             { operation }
           );
         }
@@ -538,7 +641,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               subtasks: args.subtasks,
               notes: args.notes
             };
-            const created = await kanban.doCreate(args.title, args.col || 'planned', args.epic || '—', createPayload);
+            const epicRef = args.epic_id || args.epic || '—';
+            const created = await kanban.doCreate(args.title, args.col || 'planned', epicRef, createPayload);
             const shaped = kanban.shapeTask(created, { view: 'full' });
             const warnings = kanban.createFieldWarnings(createPayload);
             result = warnings.length > 0
@@ -547,6 +651,108 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             break;
           }
 
+          case 'epic_create': {
+            const epicPayload = {
+              description: args.description,
+              goals: args.goals,
+              in_scope: args.in_scope,
+              out_of_scope: args.out_of_scope,
+              notes: args.notes
+            };
+            const createdEpic = await kanban.doCreateEpic(args.title, epicPayload);
+            const shapedEpic = kanban.shapeEpic(createdEpic, [], { view: 'full' });
+            const epicWarnings = kanban.createEpicFieldWarnings(epicPayload);
+            result = epicWarnings.length > 0
+              ? {
+                ...shapedEpic,
+                warnings: epicWarnings,
+                missing_recommended: kanban.missingRecommendedEpicCreateFields(epicPayload)
+              }
+              : shapedEpic;
+            break;
+          }
+
+          case 'epic_update': {
+            const epicId = args.epic_id || args.epic;
+            if (!epicId) {
+              throw invalidRequest(
+                "epic_id is required for 'epic_update'",
+                'Provide an epic id like E001',
+                { action }
+              );
+            }
+            const epicPatch = args.patch ? { ...args.patch } : {};
+            if (args.title !== undefined) epicPatch.title = args.title;
+            if (args.description !== undefined) epicPatch.description = args.description;
+            if (args.goals !== undefined) epicPatch.goals = args.goals;
+            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 };
+            } else if (returnShape === 'summary') {
+              result = kanban.shapeEpic(updatedEpic, await kanban.allTasks(), { view: 'summary' });
+            } else {
+              result = kanban.shapeEpic(updatedEpic, await kanban.allTasks(), { view: 'full' });
+            }
+            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(
@@ -585,7 +791,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (args.test_cases !== undefined) patch.test_cases = args.test_cases;
             if (args.subtasks !== undefined) patch.subtasks = args.subtasks;
             if (args.notes !== undefined) patch.notes = args.notes;
-            if (args.epic !== undefined) patch.epic_group = args.epic;
+            if (args.epic_id !== undefined) patch.epic_id = args.epic_id;
+            else if (args.epic !== undefined) patch.epic = args.epic;
             if (args.col !== undefined) patch.column = args.col;
             const updated = await kanban.updateTask(args.task_id, patch);
             result = formatTaskResult(updated, returnShape);
@@ -620,7 +827,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           default:
             throw invalidRequest(
               `Unknown action: ${action}`,
-              'Use create, move, update, plan_create, plan_advance, plan_evidence, plan_done, or plan_status',
+              'Use create, move, update, delete, epic_create, epic_update, epic_archive, epic_unarchive, epic_delete, plan_create, plan_advance, plan_evidence, plan_done, or plan_status',
               { action }
             );
         }

package/package.json

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

package/tests/run.js

@@ -20,3 +20,5 @@ 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');