kanbango 3.8.0 → 5.1.0

package/mcp-server.js

@@ -21,15 +21,6 @@ function activeCols() {
   return kanban.COLS.slice();
 }
 
-function transitionHint() {
-  const map = kanban.COLUMN_TRANSITIONS || {};
-  const parts = Object.keys(map).map((from) => {
-    const to = (map[from] || []).join('|');
-    return `${from}→${to || '(none)'}`;
-  });
-  return parts.join('; ') || 'see backlog/kanbango.json columns';
-}
-
 function normalizePort(value) {
   return guiRegistry.normalizeGuiPort(value);
 }
@@ -72,8 +63,37 @@ async function waitForGuiReady(pid, timeoutMs = GUI_READY_TIMEOUT_MS) {
   );
 }
 
+function nextToolCall(error) {
+  const code = error && error.code;
+  const details = (error && error.details) || {};
+
+  if (code === 'TASK_NOT_FOUND') {
+    return {
+      tool: 'kanban_read',
+      arguments: { operation: 'list', col: 'planned' }
+    };
+  }
+
+  if (code === 'INVALID_TRANSITION') {
+    const allowed = details.allowed_columns;
+    if (!Array.isArray(allowed) || allowed.length === 0 || !details.task_id) {
+      return undefined;
+    }
+    return {
+      tool: 'kanban_manage',
+      arguments: {
+        action: 'move',
+        task_id: details.task_id,
+        column: allowed[0]
+      }
+    };
+  }
+
+  return undefined;
+}
+
 function serializeError(error) {
-  return {
+  const payload = {
     error: {
       code: error.code || 'INTERNAL_ERROR',
       message: error.message,
@@ -82,6 +102,9 @@ function serializeError(error) {
       retryable: Boolean(error.retryable)
     }
   };
+  const next = nextToolCall(error);
+  if (next) payload.error.next_tool_call = next;
+  return payload;
 }
 
 function invalidRequest(message, hint, details) {
@@ -91,7 +114,7 @@ function invalidRequest(message, hint, details) {
 function serializeResult(result) {
   if (typeof result === 'string') return result;
 
-  const text = JSON.stringify(result, null, 2);
+  const text = JSON.stringify(result);
   if (typeof text === 'string') return text;
 
   throw kanban.createKanbanError(
@@ -117,7 +140,7 @@ function textResponse(result, isError = false) {
 }
 
 function normalizeReturnShape(returnShape) {
-  if (returnShape === undefined) return 'summary';
+  if (returnShape === undefined) return 'none';
   if (!['none', 'summary', 'full'].includes(returnShape)) {
     throw invalidRequest(
       `Unsupported return value: ${returnShape}`,
@@ -162,6 +185,88 @@ async function buildEpicLookup() {
   return lookup;
 }
 
+function withMissing(payload, missing) {
+  if (!missing || missing.length === 0) return payload;
+  return { ...payload, missing };
+}
+
+function formatCreateAck(id, missing) {
+  return withMissing({ ok: true, id }, missing);
+}
+
+function readFields(readOptions) {
+  if (Array.isArray(readOptions.fields) && readOptions.fields.length > 0) {
+    return readOptions.fields;
+  }
+  return kanban.VIEW_FIELDS[readOptions.view || 'summary'] || kanban.VIEW_FIELDS.summary;
+}
+
+function viewNeedsEpicLookup(readOptions) {
+  return readFields(readOptions).includes('epic_goals');
+}
+
+function viewNeedsAllTasks(readOptions) {
+  const fields = readFields(readOptions);
+  return fields.includes('blocked')
+    || fields.includes('unmet_dependencies')
+    || fields.includes('blocks');
+}
+
+function findTaskOnBoard(taskId, allTasks) {
+  const raw = String(taskId);
+  const exact = allTasks.find((task) => task.id === raw);
+  if (exact) return exact;
+  const num = parseInt(raw, 10);
+  if (!Number.isFinite(num)) return null;
+  return allTasks.find((task) => task.task_number === num) || null;
+}
+
+function omitEmptyPlanFields(payload) {
+  const out = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (value === undefined || value === null || value === '') continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+function compactPlanEvidence(evidence) {
+  if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence)) return undefined;
+  return omitEmptyPlanFields({
+    summary: evidence.summary,
+    test_command: evidence.test_command,
+    has_diff: evidence.diff ? true : undefined
+  });
+}
+
+function formatPlanResult(planResult, returnShape) {
+  if (!planResult || typeof planResult !== 'object') return planResult;
+  if (returnShape === 'full') return planResult;
+  const out = { ok: planResult.ok !== false };
+  if (planResult.task_id) out.task_id = planResult.task_id;
+  if (planResult.runner !== undefined) out.runner = planResult.runner;
+  if (planResult.current_step !== undefined && planResult.current_step !== -1) {
+    out.current_step = planResult.current_step;
+  }
+  if (planResult.status) out.status = planResult.status;
+  if (planResult.column) out.column = planResult.column;
+  if (Array.isArray(planResult.unblocked_tasks) && planResult.unblocked_tasks.length > 0) {
+    out.unblocked_tasks = planResult.unblocked_tasks;
+  }
+  if (planResult.warnings) out.warnings = planResult.warnings;
+  if (planResult.missing_recommended) out.missing = planResult.missing_recommended;
+  if (returnShape === 'none') return omitEmptyPlanFields(out);
+  if (Array.isArray(planResult.subtasks)) {
+    out.progress = {
+      done: planResult.subtasks.filter((step) => step.done).length,
+      total: planResult.subtasks.length
+    };
+  }
+  out.evidence = compactPlanEvidence(planResult.evidence);
+  return omitEmptyPlanFields(out);
+}
+
 async function formatTaskResult(task, returnShape) {
   if (returnShape === 'none') {
     if (Array.isArray(task.unblocked_tasks) && task.unblocked_tasks.length > 0) {
@@ -169,10 +274,12 @@ async function formatTaskResult(task, returnShape) {
     }
     return { ok: true };
   }
-  const epicLookup = await buildEpicLookup();
-  const allTasks = await kanban.allTasks();
+  const view = returnShape === 'full' ? 'full' : 'summary';
+  const readOptions = { view };
+  const epicLookup = viewNeedsEpicLookup(readOptions) ? await buildEpicLookup() : undefined;
+  const allTasks = viewNeedsAllTasks(readOptions) ? await kanban.allTasks() : undefined;
   const shaped = kanban.shapeTask(task, {
-    view: returnShape === 'full' ? 'full' : 'summary',
+    view,
     epicLookup,
     allTasks
   });
@@ -191,6 +298,21 @@ function guiIdentity(extra = {}) {
   };
 }
 
+function discoveredGuiPayload(discovered, extra = {}) {
+  if (!discovered) return { status: 'not_running' };
+  return guiIdentity({
+    status: extra.status || 'external_running',
+    owned: extra.owned === undefined ? false : extra.owned,
+    port: discovered.port,
+    pid: discovered.pid,
+    url: discovered.url,
+    cwd: discovered.cwd,
+    project: discovered.project,
+    started_at: discovered.started_at,
+    ...extra
+  });
+}
+
 async function startGuiServer(port) {
   if (port !== undefined && port !== null && port !== '' && !normalizePort(port)) {
     throw invalidRequest('Invalid port', 'Use an integer between 1 and 65535', { port });
@@ -277,21 +399,7 @@ async function stopGuiServer() {
 
   guiProcess = null;
   guiPort = null;
-
-  const discovered = await guiRegistry.discoverRunningGui();
-  if (!discovered) {
-    return { status: 'not_running' };
-  }
-
-  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,
+  return discoveredGuiPayload(await guiRegistry.discoverRunningGui(), {
     hint: 'GUI was not started by this MCP process; stop refused. Stop it from the owning terminal or kill that PID manually.'
   });
 }
@@ -309,22 +417,7 @@ async function guiStatus() {
 
   guiProcess = null;
   guiPort = null;
-
-  const discovered = await guiRegistry.discoverRunningGui();
-  if (!discovered) {
-    return { status: 'not_running' };
-  }
-
-  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
-  });
+  return discoveredGuiPayload(await guiRegistry.discoverRunningGui());
 }
 
 const server = new Server(
@@ -353,51 +446,35 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             operation: {
               type: 'string',
               enum: ['list', 'show', 'list_epics', 'show_epic', 'context', 'help'],
-              description: 'list/show=tasks; context=compact next action; 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,
-              description: 'Filter list by column (saves tokens — prefer this)'
-            },
-            epic: {
-              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)'
+              default: 'context'
             },
+            task_id: { type: 'string' },
+            epic_id: { type: 'string' },
+            col: { type: 'string', enum: COLS },
+            epic: { type: 'string' },
+            include_archived: { type: 'boolean' },
+            include_done: { type: 'boolean' },
             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,
-              description: 'summary=board scan (default); planning=scope/AC; execution=+subtasks; full=everything. Prefer smallest that works.'
+              enum: ['empty', 'planned', 'active', 'done', 'archived']
             },
+            view: { type: 'string', enum: READ_VIEWS },
             fields: {
               type: 'array',
-              description: 'Exact fields only (overrides view). Use when you need 1–2 fields.',
               items: { type: 'string' }
             }
           },
-          additionalProperties: false
+          additionalProperties: false,
+          examples: [
+            { operation: 'context' },
+            { operation: 'show', task_id: '014' },
+            { operation: 'list', col: 'active' }
+          ],
+          if: {
+            properties: { operation: { const: 'show' } },
+            required: ['operation']
+          },
+          then: { required: ['task_id'] }
         }
       },
       {
@@ -423,73 +500,48 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 '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, plan_create, epic_create'
+              ]
             },
+            title: { type: 'string' },
             col: {
               type: 'string',
               enum: COLS,
-              default: 'planned',
-              description: 'create column, or update shortcut for column'
+              default: 'planned'
             },
             epic: {
               type: 'string',
-              default: '—',
-              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 / epic_create)'
-            },
-            goals: {
-              type: 'string',
-              description: 'Epic outcome one-liner (recommended on epic_create)'
-            },
-            specs: {
-              type: 'string',
-              description: 'Technical constraints (recommended on create)'
+              default: '—'
             },
+            epic_id: { type: 'string' },
+            description: { type: 'string' },
+            goals: { type: 'string' },
+            specs: { type: 'string' },
             in_scope: {
               type: 'array',
-              description: 'In-scope bullets (recommended on create)',
               items: { type: 'string' }
             },
             out_of_scope: {
               type: 'array',
-              description: 'Out-of-scope bullets (recommended on create)',
               items: { type: 'string' }
             },
             acceptance_criteria: {
               type: 'array',
-              description: 'Done criteria (recommended on create)',
               items: { type: 'string' }
             },
             test_cases: {
               type: 'array',
-              description: 'Verification scenarios',
               items: { type: 'string' }
             },
             depends_on: {
               type: 'array',
-              description: 'Task ids that must be done before this task can enter active/gates',
               items: { type: 'string' }
             },
             files: {
               type: 'array',
-              description: 'Touched file paths for this task (create/update/plan_evidence)',
               items: { type: 'string' }
             },
             subtasks: {
               type: 'array',
-              description: 'Full subtask list replace on update (send complete array, not a single toggle)',
               items: {
                 type: 'object',
                 properties: {
@@ -500,13 +552,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 }
               }
             },
-            notes: {
-              type: 'string',
-              description: 'Freeform notes'
-            },
+            notes: { type: 'string' },
             adr: {
-              description:
-                'Append one ADR: { decision, why }. Or replace full array of { id?, decision, why, created? }.',
               oneOf: [
                 {
                   type: 'object',
@@ -530,67 +577,55 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 }
               ]
             },
-            task_id: {
-              type: 'string',
-              description: "Required for move/update/delete/plan_* except plan_create. '014' or '14'."
-            },
-            column: {
-              type: 'string',
-              enum: COLS,
-              description:
-                'Target column for move (not col). Must be a legal transition from the current column. '
-                + `Allowed (from project config): ${transitionHint()}. `
-                + 'Illegal → INVALID_TRANSITION + allowed_columns.'
-            },
-            patch: {
-              type: 'object',
-              description: 'Bulk update object; merged with top-level field shortcuts'
-            },
+            task_id: { type: 'string' },
+            column: { type: 'string', enum: COLS },
+            patch: { type: 'object' },
             return: {
               type: 'string',
               enum: ['none', 'summary', 'full'],
-              description: 'move/update/delete/epic_* response size. Prefer none. Default summary. create/epic_create return full once.'
-            },
-            index: {
-              type: 'integer',
-              description: 'plan_advance: subtask index; omit = first incomplete'
+              default: 'none'
             },
+            index: { type: 'integer' },
             steps: {
               type: 'array',
-              items: { type: 'string' },
-              description: 'create/plan_create: checklist texts → subtasks (create uses when subtasks omitted; plan_create uses as-is, no forced TDD steps)'
-            },
-            project_root: {
-              type: 'string',
-              description: 'plan_create: root for optional test-runner detect (default cwd); missing runner → null, not error'
-            },
-            diff: {
-              type: 'string',
-              description: 'plan_evidence: short diff or note (one of diff/summary/test_command required)'
-            },
-            summary: {
-              type: 'string',
-              description: 'plan_evidence: short implementation summary (alternative to diff)'
+              items: { type: 'string' }
             },
-            test_command: {
-              type: 'string',
-              description: 'plan_evidence: optional exact command run'
+            project_root: { type: 'string' },
+            diff: { type: 'string' },
+            summary: { type: 'string' },
+            test_command: { type: 'string' },
+            stdout: { type: 'string' },
+            stderr: { type: 'string' },
+            exit_code: { type: 'integer' }
+          },
+          required: ['action'],
+          additionalProperties: false,
+          examples: [
+            {
+              action: 'create',
+              title: 'Ship image',
+              epic: 'E001',
+              steps: ['Impl'],
+              col: 'planned'
             },
-            stdout: {
-              type: 'string',
-              description: 'plan_evidence: optional test stdout (truncate to last ~2KB if huge)'
+            { action: 'move', task_id: '014', column: 'testing' }
+          ],
+          allOf: [
+            {
+              if: {
+                properties: { action: { const: 'create' } },
+                required: ['action']
+              },
+              then: { required: ['title'] }
             },
-            stderr: {
-              type: 'string',
-              description: 'plan_evidence: optional test stderr (truncate if huge)'
-            },
-            exit_code: {
-              type: 'integer',
-              description: 'plan_evidence: optional process exit code'
+            {
+              if: {
+                properties: { action: { const: 'move' } },
+                required: ['action']
+              },
+              then: { required: ['task_id', 'column'] }
             }
-          },
-          required: ['action'],
-          additionalProperties: false
+          ]
         }
       },
       {
@@ -610,7 +645,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             }
           },
           required: ['action'],
-          additionalProperties: false
+          additionalProperties: false,
+          examples: [
+            { action: 'status' },
+            { action: 'start' }
+          ]
         }
       }
     ]
@@ -625,7 +664,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     switch (name) {
       case 'kanban_read': {
-        const operation = args.operation || 'list';
+        const operation = args.operation || 'context';
 
         if (operation === 'help') {
           result = playbook.playbookHelpPayload();
@@ -659,7 +698,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           } else {
             tasks = kanban.filterTasksForList(tasks, epics, {
               include_archived: args.include_archived,
-              include_done: args.include_done
+              include_done: args.include_done,
+              col: args.col
             });
           }
 
@@ -674,9 +714,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
 
           await kanban.migrateEpicGroups();
-          const epicLookup = await buildEpicLookup();
-          const allTasks = await kanban.allTasks();
-          result = kanban.shapeTask(await kanban.getTask(args.task_id), {
+          const needBoard = viewNeedsAllTasks(readOptions);
+          const allTasks = needBoard ? await kanban.allTasks() : undefined;
+          const task = allTasks
+            ? findTaskOnBoard(args.task_id, allTasks)
+            : await kanban.getTask(args.task_id);
+          if (!task) {
+            throw kanban.createKanbanError(
+              'TASK_NOT_FOUND',
+              `Task ${args.task_id} was not found`,
+              'Call kanban_read with operation=list to discover valid task ids',
+              { task_id: args.task_id },
+              false,
+              404
+            );
+          }
+          const epicLookup = viewNeedsEpicLookup(readOptions) ? await buildEpicLookup() : undefined;
+          result = kanban.shapeTask(task, {
             ...readOptions,
             epicLookup,
             allTasks
@@ -711,7 +765,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const epic = await kanban.getEpicEntity(link.epic_id);
           const tasks = await kanban.allTasks();
           result = kanban.shapeEpic(epic, tasks, {
-            view: args.view || 'full',
+            view: args.view || 'summary',
             fields: args.fields
           });
         } else {
@@ -754,14 +808,12 @@ 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',
-              epicLookup: await buildEpicLookup()
-            });
-            const warnings = kanban.createFieldWarnings(createPayload);
-            result = warnings.length > 0
-              ? { ...shaped, warnings, missing_recommended: kanban.missingRecommendedCreateFields(createPayload) }
-              : shaped;
+            const missing = kanban.missingRecommendedCreateFields(createPayload);
+            if (returnShape === 'none') {
+              result = formatCreateAck(created.id, missing);
+            } else {
+              result = withMissing(await formatTaskResult(created, returnShape), missing);
+            }
             break;
           }
 
@@ -774,15 +826,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               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;
+            const missing = kanban.missingRecommendedEpicCreateFields(epicPayload);
+            if (returnShape === 'none') {
+              result = formatCreateAck(createdEpic.id, missing);
+            } else {
+              const view = returnShape === 'full' ? 'full' : 'summary';
+              result = withMissing(
+                kanban.shapeEpic(createdEpic, await kanban.allTasks(), { view }),
+                missing
+              );
+            }
             break;
           }
 
@@ -862,7 +915,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             const deleted = await kanban.deleteTask(args.task_id);
             result = returnShape === 'none'
-              ? { ok: true, task_id: deleted.task_id }
+              ? { ok: true }
               : deleted;
             break;
           }
@@ -926,19 +979,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 missing_recommended: kanban.missingRecommendedCreateFields(args)
               };
             }
+            result = formatPlanResult(result, returnShape);
             break;
           }
           case 'plan_advance':
-            result = await plan.advance({ task_id: args.task_id, index: args.index });
+            result = formatPlanResult(
+              await plan.advance({ task_id: args.task_id, index: args.index }),
+              returnShape
+            );
             break;
           case 'plan_evidence':
-            result = await plan.evidence(args);
+            result = formatPlanResult(await plan.evidence(args), returnShape);
             break;
           case 'plan_done':
-            result = await plan.done({ task_id: args.task_id });
+            result = formatPlanResult(await plan.done({ task_id: args.task_id }), returnShape);
             break;
           case 'plan_status':
-            result = await plan.status(args.task_id);
+            result = formatPlanResult(await plan.status(args.task_id), returnShape === 'none' ? 'summary' : returnShape);
             break;
 
           default:
@@ -1043,6 +1100,7 @@ async function main() {
 module.exports = {
   serializeError,
   serializeResult,
+  formatPlanResult,
   textResponse,
   startGuiServer,
   stopGuiServer,

package/package.json

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