kanbango 3.1.0 → 3.2.0

package/kanban.js

@@ -63,12 +63,13 @@ const VIEW_FIELDS = {
 };
 
 const EPIC_VIEW_FIELDS = {
-  summary: ['id', 'title', 'created', 'status', 'progress'],
+  summary: ['id', 'title', 'created', 'status', 'archived', 'progress'],
   planning: [
     'id',
     'title',
     'created',
     'status',
+    'archived',
     'progress',
     'description',
     'goals',
@@ -80,6 +81,7 @@ const EPIC_VIEW_FIELDS = {
     'title',
     'created',
     'status',
+    'archived',
     'progress',
     'description',
     'goals',
@@ -90,6 +92,8 @@ const EPIC_VIEW_FIELDS = {
   ]
 };
 
+const LIVE_EPIC_STATUSES = ['empty', 'planned', 'active'];
+
 // Hard-required on create: title only (keeps GUI/CLI quick-add usable).
 // Strongly recommended for agent/planned work — missing ones yield warnings, not errors.
 const RECOMMENDED_CREATE_FIELDS = [
@@ -292,7 +296,8 @@ function normalizeEpic(epic) {
     goals: normalizeString(epic && epic.goals),
     in_scope: normalizeStringArray(epic && epic.in_scope),
     out_of_scope: normalizeStringArray(epic && epic.out_of_scope),
-    notes: normalizeString(epic && epic.notes)
+    notes: normalizeString(epic && epic.notes),
+    archived: Boolean(epic && epic.archived)
   };
 }
 
@@ -306,17 +311,26 @@ function serializeEpic(epic) {
     goals: normalized.goals,
     in_scope: normalized.in_scope,
     out_of_scope: normalized.out_of_scope,
-    notes: normalized.notes
+    notes: normalized.notes,
+    archived: normalized.archived
   };
 }
 
-function deriveEpicStatus(tasks) {
+function deriveEpicStatus(tasks, epic) {
+  if (epic && epic.archived) return 'archived';
   if (!tasks || tasks.length === 0) return 'empty';
   if (tasks.some((task) => task.column === 'active')) return 'active';
   if (tasks.every((task) => task.column === 'done')) return 'done';
   return 'planned';
 }
 
+function isLiveEpic(epicOrShaped) {
+  if (!epicOrShaped) return false;
+  if (epicOrShaped.archived) return false;
+  if (epicOrShaped.status) return LIVE_EPIC_STATUSES.includes(epicOrShaped.status);
+  return true;
+}
+
 function getEpicProgress(tasks) {
   const progress = {
     tasks_total: tasks.length,
@@ -349,7 +363,7 @@ function shapeEpic(epic, tasks = [], options = {}) {
   const childTasks = tasks.filter((task) => task.epic_id === normalized.id);
   const payload = {
     ...normalized,
-    status: deriveEpicStatus(childTasks),
+    status: deriveEpicStatus(childTasks, normalized),
     progress: getEpicProgress(childTasks),
     tasks: childTasks.map((task) => shapeTask(task, { view: 'summary' }))
   };
@@ -359,6 +373,69 @@ function shapeEpic(epic, tasks = [], options = {}) {
   return pickEpicFields(payload, fields);
 }
 
+function filterShapedEpics(shapedEpics, options = {}) {
+  const statusFilter = normalizeString(options.status).toLowerCase() || null;
+  if (statusFilter) {
+    return shapedEpics.filter((epic) => epic.status === statusFilter);
+  }
+
+  // live_only=false: human/GUI board — everything except archived unless include_archived
+  if (options.live_only === false) {
+    if (options.include_archived) return shapedEpics;
+    return shapedEpics.filter((epic) => !epic.archived);
+  }
+
+  // Default (agents): only empty|planned|active
+  const includeArchived = Boolean(options.include_archived);
+  const includeDone = Boolean(options.include_done);
+
+  return shapedEpics.filter((epic) => {
+    if (epic.archived) return includeArchived;
+    if (epic.status === 'done') return includeDone || includeArchived;
+    return isLiveEpic(epic);
+  });
+}
+
+function archivedEpicIdSet(epics) {
+  const set = new Set();
+  for (const epic of epics) {
+    if (epic.archived) set.add(epic.id);
+  }
+  return set;
+}
+
+function nonLiveEpicIdSet(epics, tasks, options = {}) {
+  const includeArchived = Boolean(options.include_archived);
+  const includeDone = Boolean(options.include_done);
+  if (includeArchived && includeDone) return new Set();
+
+  const hidden = new Set();
+  for (const epic of epics) {
+    const childTasks = tasks.filter((task) => task.epic_id === epic.id);
+    const status = deriveEpicStatus(childTasks, epic);
+    if (status === 'archived' && !includeArchived) hidden.add(epic.id);
+    else if (status === 'done' && !includeDone && !includeArchived) hidden.add(epic.id);
+  }
+  return hidden;
+}
+
+function filterTasksForList(tasks, epics, options = {}) {
+  // Explicit epic filter (show that epic's tasks) is applied by caller after this.
+  // Default agent list: hide tasks under done/archived epics.
+  if (options.include_archived && options.include_done) return tasks;
+  // GUI path: hide only archived-epic tasks (done epics still show done cards)
+  if (options.live_only === false) {
+    if (options.include_archived) return tasks;
+    const archivedIds = archivedEpicIdSet(epics);
+    if (archivedIds.size === 0) return tasks;
+    return tasks.filter((task) => !task.epic_id || !archivedIds.has(task.epic_id));
+  }
+
+  const hiddenIds = nonLiveEpicIdSet(epics, tasks, options);
+  if (hiddenIds.size === 0) return tasks;
+  return tasks.filter((task) => !task.epic_id || !hiddenIds.has(task.epic_id));
+}
+
 function getProgress(task) {
   const total = task.subtasks.length;
   const done = task.subtasks.filter((subtask) => subtask.done).length;
@@ -771,6 +848,7 @@ async function updateEpicEntity(epicId, patch) {
     next.out_of_scope = normalizeStringArray(patch.out_of_scope);
   }
   if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
+  if (patch.archived !== undefined) next.archived = Boolean(patch.archived);
 
   const saved = await writeEpic(next);
 
@@ -786,6 +864,72 @@ async function updateEpicEntity(epicId, patch) {
   return saved;
 }
 
+async function archiveEpic(epicId) {
+  return updateEpicEntity(epicId, { archived: true });
+}
+
+async function unarchiveEpic(epicId) {
+  return updateEpicEntity(epicId, { archived: false });
+}
+
+async function deleteTask(taskId) {
+  const resolvedId = await resolveTaskId(taskId);
+  const filePath = await findFile(resolvedId);
+  if (!filePath) {
+    throw createKanbanError(
+      'TASK_NOT_FOUND',
+      `Task ${taskId} was not found`,
+      'Call kanban_read with operation=list to discover valid task ids',
+      { task_id: taskId },
+      false,
+      404
+    );
+  }
+
+  const column = path.basename(path.dirname(filePath));
+  const task = await parseEpic(filePath, column);
+  await fs.unlink(filePath).catch((error) => {
+    if (error.code !== 'ENOENT') throw error;
+  });
+
+  return {
+    ok: true,
+    task_id: task.id,
+    task_number: task.task_number,
+    title: task.title,
+    column: task.column
+  };
+}
+
+async function deleteEpic(epicId) {
+  const epic = await getEpicEntity(epicId);
+  const tasks = await allTasks();
+  const children = tasks.filter((task) => task.epic_id === epic.id);
+  const deletedTasks = [];
+
+  for (const child of children) {
+    const result = await deleteTask(child.id);
+    deletedTasks.push({
+      task_id: result.task_id,
+      title: result.title,
+      column: result.column
+    });
+  }
+
+  const filePath = epicFilePath(epic.id);
+  await fs.unlink(filePath).catch((error) => {
+    if (error.code !== 'ENOENT') throw error;
+  });
+
+  return {
+    ok: true,
+    epic_id: epic.id,
+    title: epic.title,
+    deleted_tasks: deletedTasks,
+    deleted_task_count: deletedTasks.length
+  };
+}
+
 async function migrateEpicGroups(options = {}) {
   await ensureBacklogDir();
   const tasks = await allTasks();
@@ -1280,10 +1424,17 @@ module.exports = {
   doCreate,
   doCreateEpic,
   updateEpicEntity,
+  archiveEpic,
+  unarchiveEpic,
+  deleteTask,
+  deleteEpic,
   getEpicEntity,
   listEpicEntities,
   resolveEpicRef,
   taskMatchesEpicFilter,
+  filterShapedEpics,
+  filterTasksForList,
+  isLiveEpic,
   createKanbanError,
   createFieldWarnings,
   createEpicFieldWarnings,
@@ -1297,6 +1448,7 @@ module.exports = {
   STATUS_MAP,
   VIEW_FIELDS,
   EPIC_VIEW_FIELDS,
+  LIVE_EPIC_STATUSES,
   RECOMMENDED_CREATE_FIELDS,
   RECOMMENDED_EPIC_CREATE_FIELDS,
   EPICS_DIR

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(
@@ -314,6 +335,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,
@@ -340,15 +374,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 '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 daily; epic_create|epic_update for containers; plan_* for multi-step work'
+              description: 'create|move|update|delete daily; epic_create|epic_update|epic_archive|epic_unarchive|epic_delete; plan_* multi-step'
             },
             title: {
               type: 'string',
@@ -367,7 +405,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',
@@ -420,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',
@@ -434,7 +472,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',
@@ -517,13 +555,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 +589,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) {
@@ -638,6 +688,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 +702,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(
@@ -723,7 +827,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           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',
+              '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.1.0",
+  "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

@@ -21,3 +21,4 @@ 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');