kanbango 3.4.1 → 3.5.0

package/kanban.js

@@ -18,6 +18,7 @@ const VIEW_FIELDS = {
     'column',
     'epic_id',
     'epic_group',
+    'epic_goals',
     'created',
     'progress',
     'description',
@@ -33,6 +34,7 @@ const VIEW_FIELDS = {
     'column',
     'epic_id',
     'epic_group',
+    'epic_goals',
     'created',
     'progress',
     'description',
@@ -41,7 +43,8 @@ const VIEW_FIELDS = {
     'out_of_scope',
     'acceptance_criteria',
     'test_cases',
-    'subtasks'
+    'subtasks',
+    'adr'
   ],
   full: [
     'task_number',
@@ -49,6 +52,7 @@ const VIEW_FIELDS = {
     'column',
     'epic_id',
     'epic_group',
+    'epic_goals',
     'created',
     'progress',
     'description',
@@ -58,6 +62,7 @@ const VIEW_FIELDS = {
     'acceptance_criteria',
     'test_cases',
     'subtasks',
+    'adr',
     'notes'
   ]
 };
@@ -88,7 +93,8 @@ const EPIC_VIEW_FIELDS = {
     'in_scope',
     'out_of_scope',
     'notes',
-    'tasks'
+    'tasks',
+    'adrs'
   ]
 };
 
@@ -265,6 +271,60 @@ function normalizeEvidence(value) {
   }));
 }
 
+function normalizeAdr(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item, idx) => ({
+      id: normalizeString(item && item.id, `adr-${idx + 1}`),
+      decision: normalizeString(item && item.decision),
+      why: normalizeString(item && item.why),
+      created: normalizeString(item && item.created) || todayIso()
+    }))
+    .filter((item) => item.decision && item.why);
+}
+
+function nextAdrId(existing) {
+  let max = 0;
+  for (const item of existing) {
+    const match = normalizeString(item && item.id).match(/^adr-(\d+)$/i);
+    if (match) max = Math.max(max, parseInt(match[1], 10));
+  }
+  return `adr-${max + 1}`;
+}
+
+function appendAdrEntry(existing, entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw createKanbanError(
+      'VALIDATION_ERROR',
+      'adr must be an object with decision and why, or an array of such objects',
+      'Send adr: { decision: "...", why: "..." } to append one entry',
+      { field: 'adr' },
+      false,
+      400
+    );
+  }
+  const decision = normalizeString(entry.decision);
+  const why = normalizeString(entry.why);
+  if (!decision || !why) {
+    throw createKanbanError(
+      'VALIDATION_ERROR',
+      'adr.decision and adr.why must be non-empty strings',
+      'Provide both decision and why when appending an ADR',
+      { field: 'adr' },
+      false,
+      400
+    );
+  }
+  const list = normalizeAdr(existing);
+  list.push({
+    id: nextAdrId(list),
+    decision,
+    why,
+    created: normalizeString(entry.created) || todayIso()
+  });
+  return list;
+}
+
 function normalizePlan(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
   return {
@@ -291,6 +351,7 @@ function normalizeTask(task) {
     acceptance_criteria: normalizeStringArray(task.acceptance_criteria),
     test_cases: normalizeStringArray(task.test_cases),
     subtasks: normalizeSubtasks(task.subtasks),
+    adr: normalizeAdr(task.adr),
     notes: normalizeString(task.notes),
     plan: normalizePlan(task.plan),
     evidence: normalizeEvidence(task.evidence),
@@ -316,6 +377,7 @@ function serializeTask(task) {
     acceptance_criteria: normalized.acceptance_criteria,
     test_cases: normalized.test_cases,
     subtasks: normalized.subtasks,
+    adr: normalized.adr,
     notes: normalized.notes,
     plan: normalized.plan,
     evidence: normalized.evidence,
@@ -395,6 +457,24 @@ function pickEpicFields(epicPayload, fieldNames) {
   return picked;
 }
 
+function collectEpicAdrs(childTasks) {
+  const adrs = [];
+  for (const task of childTasks) {
+    const entries = normalizeAdr(task.adr);
+    for (const entry of entries) {
+      adrs.push({
+        task_id: task.id,
+        task_title: task.title,
+        id: entry.id,
+        decision: entry.decision,
+        why: entry.why,
+        created: entry.created
+      });
+    }
+  }
+  return adrs;
+}
+
 function shapeEpic(epic, tasks = [], options = {}) {
   const normalized = normalizeEpic(epic);
   const childTasks = tasks.filter((task) => task.epic_id === normalized.id);
@@ -402,7 +482,8 @@ function shapeEpic(epic, tasks = [], options = {}) {
     ...normalized,
     status: deriveEpicStatus(childTasks, normalized),
     progress: getEpicProgress(childTasks),
-    tasks: childTasks.map((task) => shapeTask(task, { view: 'summary' }))
+    tasks: childTasks.map((task) => shapeTask(task, { view: 'summary' })),
+    adrs: collectEpicAdrs(childTasks)
   };
   const fields = Array.isArray(options.fields) && options.fields.length > 0
     ? options.fields
@@ -479,6 +560,14 @@ function getProgress(task) {
   return { done, total };
 }
 
+function resolveEpicGoals(task, epicLookup) {
+  if (!task.epic_id) return '';
+  if (!epicLookup || typeof epicLookup !== 'object') return '';
+  const epic = epicLookup[task.epic_id];
+  if (!epic) return '';
+  return normalizeString(epic.goals);
+}
+
 function pickFields(task, fieldNames) {
   const picked = {};
 
@@ -487,6 +576,10 @@ function pickFields(task, fieldNames) {
       picked.progress = getProgress(task);
       continue;
     }
+    if (field === 'epic_goals') {
+      picked.epic_goals = task.epic_goals;
+      continue;
+    }
     if (field in task) {
       picked[field] = task[field];
     }
@@ -501,7 +594,11 @@ function shapeTask(task, options = {}) {
     ? options.fields
     : (VIEW_FIELDS[options.view || 'full'] || VIEW_FIELDS.full);
 
-  return pickFields(normalized, fields);
+  const withGoals = {
+    ...normalized,
+    epic_goals: resolveEpicGoals(normalized, options.epicLookup)
+  };
+  return pickFields(withGoals, fields);
 }
 
 function escapeRegex(value) {
@@ -1460,6 +1557,13 @@ async function updateTaskRecord(taskId, patch) {
     }
     next.subtasks = patch.subtasks;
   }
+  if (patch.adr !== undefined) {
+    if (Array.isArray(patch.adr)) {
+      next.adr = normalizeAdr(patch.adr);
+    } else {
+      next.adr = appendAdrEntry(next.adr, patch.adr);
+    }
+  }
   if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
   if (patch.plan !== undefined) next.plan = patch.plan;
   if (patch.evidence !== undefined) {

package/mcp-server.js

@@ -141,9 +141,22 @@ function normalizeReadOptions(args, defaultView) {
   return { view };
 }
 
-function formatTaskResult(task, returnShape) {
+async function buildEpicLookup() {
+  const epics = await kanban.listEpicEntities();
+  const lookup = {};
+  for (const epic of epics) {
+    lookup[epic.id] = epic;
+  }
+  return lookup;
+}
+
+async function formatTaskResult(task, returnShape) {
   if (returnShape === 'none') return { ok: true };
-  return kanban.shapeTask(task, { view: returnShape === 'full' ? 'full' : 'summary' });
+  const epicLookup = await buildEpicLookup();
+  return kanban.shapeTask(task, {
+    view: returnShape === 'full' ? 'full' : 'summary',
+    epicLookup
+  });
 }
 
 function guiIdentity(extra = {}) {
@@ -456,6 +469,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Freeform notes'
             },
+            adr: {
+              description:
+                'Append one ADR: { decision, why }. Or replace full array of { id?, decision, why, created? }.',
+              oneOf: [
+                {
+                  type: 'object',
+                  properties: {
+                    decision: { type: 'string' },
+                    why: { type: 'string' }
+                  },
+                  required: ['decision', 'why']
+                },
+                {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      id: { type: 'string' },
+                      decision: { type: 'string' },
+                      why: { type: 'string' },
+                      created: { type: 'string' }
+                    }
+                  }
+                }
+              ]
+            },
             task_id: {
               type: 'string',
               description: "Required for move/update/delete/plan_* except plan_create. '014' or '14'."
@@ -571,6 +610,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             });
           }
 
+          // summary omits epic_goals; no lookup needed for list tokens
           result = tasks.map((task) => kanban.shapeTask(task, readOptions));
         } else if (operation === 'show') {
           if (!args.task_id) {
@@ -581,7 +621,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             );
           }
 
-          result = kanban.shapeTask(await kanban.getTask(args.task_id), readOptions);
+          await kanban.migrateEpicGroups();
+          const epicLookup = await buildEpicLookup();
+          result = kanban.shapeTask(await kanban.getTask(args.task_id), {
+            ...readOptions,
+            epicLookup
+          });
         } else if (operation === 'list_epics') {
           await kanban.migrateEpicGroups();
           const tasks = await kanban.allTasks();
@@ -643,7 +688,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
             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 shaped = kanban.shapeTask(created, {
+              view: 'full',
+              epicLookup: await buildEpicLookup()
+            });
             const warnings = kanban.createFieldWarnings(createPayload);
             result = warnings.length > 0
               ? { ...shaped, warnings, missing_recommended: kanban.missingRecommendedCreateFields(createPayload) }
@@ -769,7 +817,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               );
             }
             const updated = await kanban.updateTask(args.task_id, { column: args.column });
-            result = formatTaskResult(updated, returnShape);
+            result = await formatTaskResult(updated, returnShape);
             break;
           }
 
@@ -791,11 +839,12 @@ 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.adr !== undefined) patch.adr = args.adr;
             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);
+            result = await formatTaskResult(updated, returnShape);
             break;
           }
 
@@ -892,8 +941,8 @@ function installGuiShutdownHooks() {
     if (!ownsGuiProcess()) return;
     try {
       await stopGuiServer();
-    } catch {
-      // best-effort
+    } catch (error) {
+      console.error(`kanbango GUI shutdown failed: ${error.message}`);
     }
   }
 
@@ -901,8 +950,8 @@ function installGuiShutdownHooks() {
     if (ownsGuiProcess()) {
       try {
         guiProcess.kill();
-      } catch {
-        // ignore
+      } catch (error) {
+        console.error(`kanbango GUI kill on exit failed: ${error.message}`);
       }
     }
   });

package/package.json

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

package/tests/run.js

@@ -18,10 +18,12 @@ runNode(path.join('tests', 'update-tasks.test.js'), [], 'Update tasks 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', 'gui-cockpit.test.js'), [], 'GUI cockpit layout + workflow test');
 runNode(path.join('tests', 'fenced-text.test.js'), [], 'Fenced text test');
 runNode(path.join('tests', 'kanban-mermaid-vendor.test.js'), [], 'Kanban mermaid vendor route 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', 'kanban-epic-goals-adr.test.js'), [], 'Epic goals + ADR test');
 runNode(path.join('tests', 'delete-archive.test.js'), [], 'Delete/archive test');
 runNode(path.join('tests', 'race-conditions.test.js'), [], 'Race conditions test');