kanbango 3.3.0 → 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',
@@ -42,7 +44,7 @@ const VIEW_FIELDS = {
     'acceptance_criteria',
     'test_cases',
     'subtasks',
-    'comments'
+    'adr'
   ],
   full: [
     'task_number',
@@ -50,6 +52,7 @@ const VIEW_FIELDS = {
     'column',
     'epic_id',
     'epic_group',
+    'epic_goals',
     'created',
     'progress',
     'description',
@@ -59,8 +62,8 @@ const VIEW_FIELDS = {
     'acceptance_criteria',
     'test_cases',
     'subtasks',
-    'notes',
-    'comments'
+    'adr',
+    'notes'
   ]
 };
 
@@ -90,7 +93,8 @@ const EPIC_VIEW_FIELDS = {
     'in_scope',
     'out_of_scope',
     'notes',
-    'tasks'
+    'tasks',
+    'adrs'
   ]
 };
 
@@ -255,28 +259,6 @@ function normalizeSubtasks(value) {
   })).filter((subtask) => subtask.text);
 }
 
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function nextCommentId(comments) {
-  const max = comments.reduce((highest, comment) => {
-    const match = String(comment && comment.id || '').match(/^c-(\d+)$/i);
-    return match ? Math.max(highest, parseInt(match[1], 10)) : highest;
-  }, 0);
-  return `c-${max + 1}`;
-}
-
-function normalizeComments(value) {
-  if (!Array.isArray(value)) return [];
-  return value.map((item, idx) => ({
-    id: normalizeString(item && item.id, `c-${idx + 1}`),
-    created: normalizeString(item && item.created) || nowIso(),
-    author: normalizeString(item && item.author, 'user') || 'user',
-    text: normalizeString(item && item.text)
-  })).filter((item) => item.text);
-}
-
 function normalizeEvidence(value) {
   if (!Array.isArray(value)) return [];
   return value.map((item) => ({
@@ -289,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 {
@@ -315,8 +351,8 @@ 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),
-    comments: normalizeComments(task.comments),
     plan: normalizePlan(task.plan),
     evidence: normalizeEvidence(task.evidence),
     task_number: extractTaskNumber(id)
@@ -341,8 +377,8 @@ function serializeTask(task) {
     acceptance_criteria: normalized.acceptance_criteria,
     test_cases: normalized.test_cases,
     subtasks: normalized.subtasks,
+    adr: normalized.adr,
     notes: normalized.notes,
-    comments: normalized.comments,
     plan: normalized.plan,
     evidence: normalized.evidence,
     task_number: normalized.task_number
@@ -421,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);
@@ -428,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
@@ -505,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 = {};
 
@@ -513,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];
     }
@@ -527,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) {
@@ -1341,7 +1412,6 @@ async function doCreate(title, column = 'planned', epicRef = '—', extra = {})
         test_cases: extra.test_cases,
         subtasks: extra.subtasks,
         notes: extra.notes,
-        comments: extra.comments,
         plan: extra.plan,
         evidence: extra.evidence
       });
@@ -1487,20 +1557,14 @@ async function updateTaskRecord(taskId, patch) {
     }
     next.subtasks = patch.subtasks;
   }
-  if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
-  if (patch.comments !== undefined) {
-    if (!Array.isArray(patch.comments)) {
-      throw createKanbanError(
-        'VALIDATION_ERROR',
-        'comments must be an array',
-        'Send comments as an array of comment objects',
-        { field: 'comments' },
-        false,
-        400
-      );
+  if (patch.adr !== undefined) {
+    if (Array.isArray(patch.adr)) {
+      next.adr = normalizeAdr(patch.adr);
+    } else {
+      next.adr = appendAdrEntry(next.adr, patch.adr);
     }
-    next.comments = patch.comments;
   }
+  if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
   if (patch.plan !== undefined) next.plan = patch.plan;
   if (patch.evidence !== undefined) {
     if (!Array.isArray(patch.evidence)) {
@@ -1524,44 +1588,6 @@ async function updateTask(taskId, patch) {
   return withBoardLock(() => updateTaskRecord(taskId, patch));
 }
 
-async function addComment(taskId, text, author = 'user') {
-  const body = normalizeString(text);
-  if (!body) {
-    throw createKanbanError(
-      'MISSING_REQUIRED_FIELD',
-      'text is required',
-      'Provide a non-empty comment text',
-      { field: 'text' },
-      false,
-      400
-    );
-  }
-  return withBoardLock(async () => {
-    const resolvedId = await resolveTaskId(taskId);
-    const previousFilePath = await findFile(resolvedId);
-    if (!previousFilePath) {
-      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 current = await parseEpic(previousFilePath, path.basename(path.dirname(previousFilePath)));
-    const comments = normalizeComments(current.comments);
-    const comment = {
-      id: nextCommentId(comments),
-      created: nowIso(),
-      author: normalizeString(author, 'user') || 'user',
-      text: body
-    };
-    const saved = await writeTask({ ...current, comments: [...comments, comment] }, previousFilePath);
-    return { comment, comments: saved.comments, task_id: saved.id };
-  });
-}
-
 async function doMove(epicId, target) {
   try {
     await updateTask(epicId, { column: target });
@@ -1627,7 +1653,6 @@ module.exports = {
   shapeTask,
   shapeEpic,
   updateTask,
-  addComment,
   migrateAll,
   migrateEpicGroups,
   doMove,

package/mcp-server.js

@@ -76,101 +76,6 @@ 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;
 
@@ -236,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 = {}) {
@@ -465,8 +383,23 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             action: {
               type: 'string',
-              enum: MANAGE_ACTIONS,
-              description: 'create|move|update|delete daily; epic_*; plan_*; comment_add'
+              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',
@@ -536,17 +469,35 @@ 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'
+            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/comment_add/plan_* except plan_create. '014' or '14'."
+              description: "Required for move/update/delete/plan_* except plan_create. '014' or '14'."
             },
             column: {
               type: 'string',
@@ -608,7 +559,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             action: {
               type: 'string',
-              enum: GUI_ACTIONS,
+              enum: ['start', 'stop', 'status'],
               description: 'start | stop (owned only) | status'
             },
             port: {
@@ -659,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) {
@@ -669,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();
@@ -714,7 +671,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'kanban_manage': {
-        const action = requireToolAction(args, MANAGE_ACTIONS, 'kanban_manage');
+        const action = args.action;
         const returnShape = normalizeReturnShape(args.return);
 
         switch (action) {
@@ -731,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) }
@@ -857,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;
           }
 
@@ -879,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;
           }
 
@@ -912,38 +873,18 @@ 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 unknownToolAction(action, args, MANAGE_ACTIONS, 'kanban_manage');
+            throw invalidRequest(
+              `Unknown action: ${action}`,
+              '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 }
+            );
         }
         break;
       }
 
       case 'kanban_gui': {
-        const action = requireToolAction(args, GUI_ACTIONS, 'kanban_gui');
+        const action = args.action;
 
         switch (action) {
           case 'start': {
@@ -959,7 +900,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             break;
           }
           default:
-            throw unknownToolAction(action, args, GUI_ACTIONS, 'kanban_gui');
+            throw invalidRequest(
+              `Unknown action: ${action}`,
+              'Use one of: start, stop, status',
+              { action }
+            );
         }
         break;
       }
@@ -996,8 +941,8 @@ function installGuiShutdownHooks() {
     if (!ownsGuiProcess()) return;
     try {
       await stopGuiServer();
-    } catch {
-      // best-effort
+    } catch (error) {
+      console.error(`kanbango GUI shutdown failed: ${error.message}`);
     }
   }
 
@@ -1005,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.3.0",
+  "version": "3.5.0",
   "description": "JSON-first local Kanban board with web GUI, CLI, and MCP server",
   "main": "index.js",
   "bin": {
@@ -36,6 +36,7 @@
     "node": ">=16.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "mermaid": "^11.17.0"
   }
 }

package/tests/run.js

@@ -15,12 +15,15 @@ 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', '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');