kanbango 2.0.0 → 2.4.0

package/README.md

@@ -1,267 +1,92 @@
 # kanbango
 
-JSON-first local Kanban board with web GUI, CLI, and MCP server (pure JavaScript).
-
-## Features
-
-- 📊 Local Kanban board stored in JSON task files
-- 🎨 Modern web GUI with drag-and-drop interface
-- 🖥️ Full CLI support for automation and CI/CD
-- 🤖 AI-friendly API (JSON output)
-- 📁 Four columns: Active, Planned, Icebox, Done
-- ✅ Subtasks with progress tracking
-- 🏷️ Epic grouping
+JSON-first local Kanban board for developers and AI agents — CLI, web GUI, and MCP server in one lightweight package.
 
 ## Installation
 
-### Global (recommended)
+### Global (recommended for CLI)
 ```bash
 npm install -g kanbango
 ```
 
-### Local (per project)
+### Local per project (recommended for MCP)
 ```bash
 npm install -D kanbango
 ```
 
-### Using npx (no installation)
+### No install
 ```bash
 npx kanbango --help
 ```
 
-## NPM Package
-
-- Package name: `kanbango`
-- Binaries: `kanban`, `kanban-cmd`
-- MCP server entrypoint: `mcp-server.js` (run via `npx kanbango mcp`)
-
-## Requirements
-
-- Node.js 16+
-
 ## Quick Start
 
 ```bash
-# Initialize backlog structure
+# Initialize backlog directories
 kanban init
 
-# Start web GUI (opens http://localhost:5500)
+# Start web GUI (stable project port; prints the real URL)
 kanban serve
 
-# List all tasks (JSON)
+# List all tasks
 kanban list --json
 
-# Add a new task
-kanban add "New feature" --col planned --epic "Phase1"
+# Add a task
+kanban add "My task" --col planned --epic "Phase 1"
 
-# Show task details
-kanban show PI-001
+# Show details
+kanban show 001
 
-# Move task between columns
-kanban move PI-001 active
+# Move between columns (active | planned | icebox | done)
+kanban move 001 active
 
-# Toggle subtask
-kanban toggle PI-001 0
+# Update subtasks in one call
+kanban update 001 '{"subtasks":[{"done":true,"text":"Research"},{"done":false,"text":"Implementation"}]}'
 ```
 
-## CLI Commands
+### Columns
 
-| Command | Description |
-|---------|-------------|
-| `kanban serve [PORT]` | Start web GUI (default: 5500) |
-| `kanban init` | Initialize backlog structure |
-| `kanban mcp-init` | Generate MCP config files for Claude Code / OpenCode |
-| `kanban list` | List all tasks |
-| `kanban show <ID>` | Show task details |
-| `kanban add <TITLE>` | Add new task |
-| `kanban move <ID> <COL>` | Move task to column |
-| `kanban toggle <ID> <IDX>` | Toggle subtask |
-
-## Columns
-
-- `active` — In progress (max 1-2 tasks)
-- `planned` — Planned for implementation
-- `icebox` — Frozen / nice-to-have
-- `done` — Completed
+| Column | Purpose |
+|--------|---------|
+| `active` | In progress (keep to 1–2 tasks) |
+| `planned` | Ready to implement |
+| `icebox` | Nice-to-have / frozen |
+| `done` | Completed |
 
 ## Data Structure
 
-Tasks are stored as JSON files in `backlog/<column>/`. Existing Markdown task files are still readable during migration:
+Tasks are JSON files in `backlog/<column>/`:
 
 ```json
 {
-  "id": "PI-001-feature-title",
-  "title": "Feature Title",
+  "id": "001",
+  "title": "My Feature",
   "column": "planned",
   "epic_group": "Phase 1",
-  "created": "2026-07-07",
-  "description": "High-level context and implementation plan.",
-  "specs": "Technical details and constraints.",
-  "acceptance_criteria": [
-    "First condition",
-    "Second condition"
-  ],
+  "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 subtask",
-      "done": false,
-      "description": "Execution details for the subtask"
-    }
-  ],
-  "notes": "Optional freeform notes"
-}
-```
-
-## AI Integration
-
-The `kanban-cmd` command provides simplified JSON output for AI agents:
-
-```bash
-# For AI: always use JSON output
-kanban-cmd list
-
-# Filter by column
-kanban-cmd list --col active
-
-# Show task details
-kanban-cmd show PI-001
-
-# Add task (AI-friendly)
-kanban-cmd add "New task" --col planned --epic "Phase 1"
-```
-
-### JSON Output Format
-
-```json
-[
-  {
-    "id": "PI-001-feature-title",
-    "title": "Feature Title",
-    "column": "planned",
-    "epic_group": "Phase 1",
-    "created": "2026-07-07",
-    "description": "High-level context and implementation plan.",
-    "specs": "Technical details and constraints.",
-    "acceptance_criteria": [
-      "First condition"
-    ],
-    "tasks": [
-      {
-        "id": "st-1",
-        "done": false,
-        "text": "First subtask",
-        "description": "Execution details for the subtask"
-      }
-    ]
-  }
-]
-```
-
-## MCP Task Views
-
-`kanban_read` supports compact response shaping so agents can avoid reading the whole task every time.
-
-```json
-{
-  "operation": "show",
-  "task_id": "PI-001-feature-title",
-  "view": "planning"
-}
-```
-
-Supported views:
-
-- `summary` - `id`, `title`, `column`, `epic_group`, `created`, `progress`
-- `planning` - summary + `description`, `specs`, `acceptance_criteria`
-- `execution` - planning + `subtasks`
-- `full` - execution + `notes`
-
-You can also request explicit fields:
-
-```json
-{
-  "operation": "show",
-  "task_id": "PI-001-feature-title",
-  "fields": ["title", "description", "acceptance_criteria"]
-}
-```
-
-`kanban_update` supports patch-style updates and compact responses:
-
-```json
-{
-  "operation": "update",
-  "task_id": "PI-001-feature-title",
-  "patch": {
-    "description": "Updated plan",
-    "acceptance_criteria": ["OAuth works"]
-  },
-  "return": "summary"
-}
-```
-
-Errors are returned as structured JSON:
-
-```json
-{
-  "error": {
-    "code": "TASK_NOT_FOUND",
-    "message": "Task PI-999-missing was not found",
-    "hint": "Call kanban_read with operation=list to discover valid task ids",
-    "details": {
-      "task_id": "PI-999-missing"
-    },
-    "retryable": false
-  }
+    { "id": "st-1", "text": "First step", "done": false }
+  ]
 }
 ```
 
-## Web GUI
-
-Start the web interface:
-```bash
-kanban serve 5500
-```
-
-Features:
-- Swimlanes grouped by epic
-- Drag-and-drop between columns
-- Inline editing
-- Real-time subtask checkboxes
-- Progress tracking
-
-## Directory Structure
-
-```
-backlog/
-├── active/    # Tasks in progress
-├── planned/   # Planned tasks
-├── icebox/    # Frozen tasks
-└── done/      # Completed tasks
-```
-
-## API for AI Agents
-
-See [API.md](API.md) for detailed API function definitions.
-
-## MCP Server
+## MCP Server (for Claude Code, OpenCode, Cursor)
 
-This package includes a Model Context Protocol (MCP) server for integration with MCP-compatible clients.
-
-### Using the MCP server
+Run the MCP server to let AI agents read / create / update your board:
 
 ```bash
-# Run the MCP server directly
-npm run mcp
-
-# Or using npx
 npx kanbango mcp
 ```
 
-### MCP Configuration
+### Give it to your agent
 
-For MCP clients, add this to your configuration:
+Add this to your MCP client config (`.mcp.json`, `opencode.json`, or Claude Desktop config):
 
 ```json
 {
@@ -274,87 +99,74 @@ For MCP clients, add this to your configuration:
 }
 ```
 
-### MCP Per Project (Recommended)
-
-Install locally in the project so each repo controls its own MCP version:
-
-```bash
-npm install -D kanbango
-```
-
-Then point MCP to the local package:
-
-```json
-{
-  "mcpServers": {
-    "kanbango": {
-      "command": "node",
-      "args": ["./node_modules/kanbango/mcp-server.js"]
-    }
-  }
-}
-```
-
-If you prefer `npx`, you can still use it, but versioning is less explicit:
+Auto-start the web GUI with MCP (opt-in):
 
 ```json
 {
   "mcpServers": {
     "kanbango": {
       "command": "npx",
-      "args": ["kanbango", "mcp"]
+      "args": ["kanbango", "mcp"],
+      "env": {
+        "KANBANGO_AUTO_GUI": "1"
+      }
     }
   }
 }
 ```
 
-### MCP Project Automation (Claude Code + OpenCode)
+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).
 
-Generate project configs automatically (creates `.mcp.json` and `opencode.json` in the current folder):
+Or generate the config files automatically:
 
 ```bash
-# Local install (recommended)
 npx kanbango mcp-init
+```
 
-# Use npx-based command in configs
-npx kanbango mcp-init --npx
+### What the agent can do
 
-# Only Claude Code config
-npx kanbango mcp-init --claude
+Once connected, your agent gets access to these tools:
 
-# Only OpenCode config
-npx kanbango mcp-init --opencode
+| Tool | What it does |
+|------|-------------|
+| `kanban_read` | List tasks, filter by column/epic, show details |
+| `kanban_manage` | Create, move, patch-update tasks |
+| `kanban_gui` | Start, stop, or check web GUI status (returns the real URL/port) |
 
-# Overwrite existing files
-npx kanbango mcp-init --force
-```
+Your agent stays in sync with your real board — every change is persisted as JSON files.
 
-### Available MCP Tools
+## CLI Reference
 
-- `kanban_read` - Read tasks (list all, filter, or get specific task details)
-- `kanban_create` - Create a new task
-- `kanban_update` - Update tasks (move, toggle subtask, or edit details)
-- `kanban_gui_start` - Start the web GUI server (returns URL)
-- `kanban_gui_stop` - Stop the web GUI server
-- `kanban_gui_status` - Check GUI server status
+| Command | Description |
+|---------|-------------|
+| `kanban init` | Create backlog directory structure |
+| `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 mcp-init` | Generate MCP config files |
 
-## Development
+## Web GUI
 
 ```bash
-# Install dependencies
-npm install
+kanban serve
+```
+- Swimlanes grouped by epic
+- Drag-and-drop between columns
+- Inline editing and subtask checkboxes
 
-# Run tests
-npm test
+## Using as a Node.js module
 
-# Build (if needed)
-npm run build
+```js
+const kanban = require('kanbango');
+const tasks = await kanban.allEpics();
 ```
 
-## License
+## Requirements
 
-MIT
+Node.js 16+
 
-## Contributing
+## License
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+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);