kanbango 2.1.0 → 2.4.0

package/README.md

@@ -25,7 +25,7 @@ npx kanbango --help
 # Initialize backlog directories
 kanban init
 
-# Start web GUI at http://localhost:5500
+# Start web GUI (stable project port; prints the real URL)
 kanban serve
 
 # List all tasks
@@ -35,13 +35,13 @@ kanban list --json
 kanban add "My task" --col planned --epic "Phase 1"
 
 # Show details
-kanban show PI-001
+kanban show 001
 
 # Move between columns (active | planned | icebox | done)
-kanban move PI-001 active
+kanban move 001 active
 
-# Toggle subtask completion
-kanban toggle PI-001 0
+# Update subtasks in one call
+kanban update 001 '{"subtasks":[{"done":true,"text":"Research"},{"done":false,"text":"Implementation"}]}'
 ```
 
 ### Columns
@@ -59,14 +59,17 @@ Tasks are JSON files in `backlog/<column>/`:
 
 ```json
 {
-  "id": "PI-001-my-feature",
+  "id": "001",
   "title": "My Feature",
   "column": "planned",
   "epic_group": "Phase 1",
   "created": "2026-07-08",
   "description": "High-level context.",
   "specs": "Technical details.",
+  "in_scope": ["What this task covers"],
+  "out_of_scope": ["What is explicitly excluded"],
   "acceptance_criteria": ["Works as expected"],
+  "test_cases": ["Verify the happy path"],
   "subtasks": [
     { "id": "st-1", "text": "First step", "done": false }
   ]
@@ -96,6 +99,24 @@ Add this to your MCP client config (`.mcp.json`, `opencode.json`, or Claude Desk
 }
 ```
 
+Auto-start the web GUI with MCP (opt-in):
+
+```json
+{
+  "mcpServers": {
+    "kanbango": {
+      "command": "npx",
+      "args": ["kanbango", "mcp"],
+      "env": {
+        "KANBANGO_AUTO_GUI": "1"
+      }
+    }
+  }
+}
+```
+
+Optional: pin the port with `KANBANGO_GUI_PORT` (e.g. `"5821"`). Without it, each project gets a stable port in `5510–5999` derived from the project path. The real URL is always available via `kanban_gui` → `status` (and written to `backlog/.kanbango-gui.json` while the GUI runs).
+
 Or generate the config files automatically:
 
 ```bash
@@ -109,11 +130,8 @@ Once connected, your agent gets access to these tools:
 | Tool | What it does |
 |------|-------------|
 | `kanban_read` | List tasks, filter by column/epic, show details |
-| `kanban_create` | Add new tasks |
-| `kanban_update` | Move, edit, toggle subtasks |
-| `kanban_gui_start` | Start web GUI from the agent |
-| `kanban_gui_stop` | Stop web GUI |
-| `kanban_gui_status` | Check if GUI is running |
+| `kanban_manage` | Create, move, patch-update tasks |
+| `kanban_gui` | Start, stop, or check web GUI status (returns the real URL/port) |
 
 Your agent stays in sync with your real board — every change is persisted as JSON files.
 
@@ -122,12 +140,11 @@ Your agent stays in sync with your real board — every change is persisted as J
 | Command | Description |
 |---------|-------------|
 | `kanban init` | Create backlog directory structure |
-| `kanban serve [PORT]` | Start web GUI (default 5500) |
+| `kanban serve [PORT]` | Start web GUI (stable project port, or PORT / KANBANGO_GUI_PORT) |
 | `kanban list [--col <col>] [--json]` | List tasks |
 | `kanban show <ID>` | Show task details |
 | `kanban add <TITLE>` | Add a new task |
 | `kanban move <ID> <COL>` | Move task |
-| `kanban toggle <ID> <IDX>` | Toggle subtask |
 | `kanban mcp-init` | Generate MCP config files |
 
 ## Web GUI
@@ -152,4 +169,4 @@ Node.js 16+
 
 ## License
 
-MIT
+MIT

package/bin/kanban.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const kanban = require('../kanban.js');
+const plan = require('../plan.js');
 const http = require('http');
 const fs = require('fs');
 const path = require('path');
@@ -9,7 +10,7 @@ const BACKLOG = path.join(process.cwd(), 'backlog');
 const COLS = kanban.COLS;
 
 function shortId(taskId) {
-  const match = taskId.match(/^(PI-\d+[\w.-]*|BUG-\d+|CHORE-\d+)/);
+  const match = taskId.match(/^(?:[A-Z]+-)?(\d+)/);
   return match ? match[1] : taskId;
 }
 
@@ -222,21 +223,6 @@ async function cliAdd(title, column, epicGroup) {
   }
 }
 
-async function cliToggle(taskId, idx) {
-  const success = await kanban.doToggle(taskId, idx);
-  if (!success) {
-    console.error(`✗ Nie znaleziono: ${taskId} subtask ${idx}`);
-    process.exit(1);
-  }
-
-  const task = await kanban.getTask(taskId);
-  if (idx < task.subtasks.length) {
-    const subtask = task.subtasks[idx];
-    const mark = subtask.done ? '✓' : '○';
-    console.log(`  [${idx}] ${mark} ${subtask.text}`);
-  }
-}
-
 async function serveWeb(port) {
   const html = fs.readFileSync(path.join(__dirname, '..', 'index.html'), 'utf-8');
 
@@ -262,7 +248,10 @@ async function serveWeb(port) {
         const task = await kanban.doCreate(body.title || '', body.column || 'planned', body.epic_group || '—', {
           description: body.description,
           specs: body.specs,
+          in_scope: body.in_scope,
+          out_of_scope: body.out_of_scope,
           acceptance_criteria: body.acceptance_criteria,
+          test_cases: body.test_cases,
           subtasks: body.subtasks,
           notes: body.notes
         });
@@ -312,10 +301,12 @@ async function serveWeb(port) {
           const patch = body.patch ? { ...body.patch } : {};
 
           if (body.title !== undefined) patch.title = body.title;
-          if (body.tasks !== undefined) patch.subtasks = body.tasks;
           if (body.description !== undefined) patch.description = body.description;
           if (body.specs !== undefined) patch.specs = body.specs;
+          if (body.in_scope !== undefined) patch.in_scope = body.in_scope;
+          if (body.out_of_scope !== undefined) patch.out_of_scope = body.out_of_scope;
           if (body.acceptance_criteria !== undefined) patch.acceptance_criteria = body.acceptance_criteria;
+          if (body.test_cases !== undefined) patch.test_cases = body.test_cases;
           if (body.subtasks !== undefined) patch.subtasks = body.subtasks;
           if (body.notes !== undefined) patch.notes = body.notes;
           if (body.epic_group !== undefined) patch.epic_group = body.epic_group;
@@ -332,11 +323,66 @@ async function serveWeb(port) {
     }
   });
 
-  server.listen(port, 'localhost', () => {
-    console.log(`\x1b[1;32m→ Kanban GUI: http://localhost:${port}\x1b[0m`);
-    console.log(`  Backlog:   ${BACKLOG}`);
-    console.log('  Ctrl+C żeby zamknąć');
+  const MAX_ATTEMPTS = 10;
+
+  function listenOnce(server, port) {
+    return new Promise((resolve, reject) => {
+      function onError(err) {
+        server.removeListener('listening', onListening);
+        reject(err);
+      }
+      function onListening() {
+        server.removeListener('error', onError);
+        resolve();
+      }
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(port, 'localhost');
+    });
+  }
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    try {
+      await listenOnce(server, port + attempt);
+      break;
+    } catch (err) {
+      if (err.code !== 'EADDRINUSE') throw err;
+      console.log(`Port ${port + attempt} zajęty, próbuję ${port + attempt + 1}…`);
+    }
+  }
+
+  if (!server.listening) {
+    console.log(`Porty ${port}–${port + MAX_ATTEMPTS - 1} zajęte, próbuję losowy port…`);
+    await listenOnce(server, 0);
+  }
+
+  const actualPort = server.address().port;
+  const portInfo = await kanban.writeGuiPortFile({ port: actualPort, pid: process.pid });
+
+  async function cleanupGuiPortFile() {
+    try {
+      await kanban.clearGuiPortFile({ pid: process.pid });
+    } catch {
+      // best-effort cleanup
+    }
+  }
+
+  server.on('close', () => {
+    cleanupGuiPortFile();
   });
+
+  process.once('SIGINT', async () => {
+    await cleanupGuiPortFile();
+    server.close(() => process.exit(0));
+  });
+  process.once('SIGTERM', async () => {
+    await cleanupGuiPortFile();
+    server.close(() => process.exit(0));
+  });
+
+  console.log(`\x1b[1;32m→ Kanban GUI: ${portInfo.url}\x1b[0m`);
+  console.log(`  Backlog:   ${BACKLOG}`);
+  console.log('  Ctrl+C żeby zamknąć');
 }
 
 function readBody(req) {
@@ -379,13 +425,42 @@ async function cliMigrate(dryRun) {
   }
 }
 
+function parseJsonPayload(value) {
+  try {
+    return JSON.parse(value || '{}');
+  } catch (error) {
+    throw kanban.createKanbanError('INVALID_JSON', 'Payload is not valid JSON',
+      'Pass a JSON object after --json', { reason: error.message }, false, 400);
+  }
+}
+
+async function cliPlan(action, payload) {
+  try {
+    const handlers = {
+      create: plan.create,
+      advance: plan.advance,
+      evidence: plan.evidence,
+      done: plan.done,
+      status: (input) => plan.status(input.task_id)
+    };
+    if (!handlers[action]) throw kanban.createKanbanError('INVALID_PLAN_ACTION', `Unknown plan action: ${action}`,
+      'Use create, advance, evidence, done, or status', { action }, false, 400);
+    console.log(JSON.stringify(await handlers[action](payload)));
+  } catch (error) {
+    console.log(JSON.stringify({ ok: false, task_id: payload.task_id || null, subtasks: [], error: {
+      code: error.code || 'INTERNAL_ERROR', message: error.message, hint: error.hint || '', details: error.details || {}
+    } }));
+    process.exitCode = 1;
+  }
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const cmd = args[0];
 
-  if (!cmd || cmd === 'serve') {
-    const port = parseInt(args[1] || '5500', 10);
-    await serveWeb(port);
+if (!cmd || cmd === 'serve') {
+  const port = kanban.resolvePreferredGuiPort(args[1]);
+  await serveWeb(port);
   } else if (cmd === 'init') {
     await cliInit();
   } else if (cmd === 'mcp-init') {
@@ -448,8 +523,8 @@ async function main() {
     }
 
     await cliAdd(args[1], column, epicGroup);
-  } else if (cmd === 'toggle' && args[1] && args[2]) {
-    await cliToggle(args[1], parseInt(args[2], 10));
+  } else if (cmd === 'plan' && args[1] && args[2] === '--json') {
+    await cliPlan(args[1], parseJsonPayload(args[3]));
   } else {
     console.error('Unknown command:', cmd);
     process.exit(1);