kanbango 2.1.0 → 2.5.0

package/index.js

@@ -9,7 +9,9 @@
  */
 
 const kanban = require('./kanban.js');
+const plan = require('./plan.js');
 
 module.exports = {
   kanban,
+  plan,
 };

package/kan2.md

@@ -0,0 +1,76 @@
+# Plan kan2: Kanbango Plan Workflow
+
+## Cel
+
+Rozszerzyć Kanbango o niezależny workflow planów, który może być używany przez
+OpenCode, inne agenty i CLI. Kanbango pozostaje osobnym repozytorium.
+
+## Zasada architektoniczna
+
+Kanbango nie zna API OpenCode ani hooków pluginu. Udostępnia stabilne operacje
+na planie i evidence. Plugin OpenCode jest tylko klientem oraz strażnikiem sesji.
+
+## Funkcjonalność
+
+Dodać bibliotekę domenową oraz odpowiednie operacje CLI/MCP:
+
+- utworzenie taska z zaakceptowanym planem,
+- zapis kroków planu jako subtasks,
+- oznaczenie bieżącego kroku jako zakończonego,
+- zapis evidence: diff, komenda testowa, stdout, stderr i exit code,
+- zakończenie workflow i przeniesienie taska do `done`,
+- odczyt pełnego statusu planu w stabilnym formacie JSON.
+
+## Domyślne kroki
+
+Każdy zaakceptowany plan dostaje kolejno:
+
+1. `Write tests`
+2. `Run tests and confirm red`
+3. Kroki implementacyjne dostarczone przez advisora
+4. `Run tests and confirm green`
+
+## Test runner
+
+Autodetekcja musi działać per projekt, bez założenia Node:
+
+- Rust: `cargo test` przy `Cargo.toml`,
+- Go: `go test ./...` przy `go.mod`,
+- Python: `python -m pytest` przy `pyproject.toml` lub `pytest.ini`,
+- JavaScript/TypeScript: `npm test`, `pnpm test`, `yarn test` albo `bun test`
+  zgodnie z lockfilem i skryptem `test` w `package.json`,
+- jawny override przez `OPENCODE_TEST_COMMAND`.
+
+Autodetekcja ma zwracać także powód wyboru komendy i czytelny błąd, gdy nie
+znaleziono testów.
+
+## Interfejs
+
+Preferowany jest wspólny moduł JS oraz JSON CLI/MCP, zamiast parsowania tekstu:
+
+- `plan create --json <payload>`,
+- `plan advance --json <payload>`,
+- `plan evidence --json <payload>`,
+- `plan done --json <payload>`,
+- odpowiadające operacje w `kanban_manage` lub osobnym narzędziu MCP.
+
+CLI musi zwracać stabilny JSON z `ok`, `task_id`, `subtasks` i `error`.
+
+## Testy TDD
+
+- autodetekcja runnera dla Rust, Go, Python i Node,
+- utworzenie planu z czterema grupami kroków,
+- aktualizacja kroku bez kasowania pozostałych subtasks,
+- zapis evidence bez silent fail,
+- zakończenie planu i przejście do `done`,
+- błędna komenda testowa i brak testów,
+- wywołanie przez CLI i MCP z tym samym rezultatem.
+
+## Kolejność implementacji
+
+1. Model planu i runner detection.
+2. Operacje biblioteki Kanbango.
+3. CLI i JSON output.
+4. MCP adapter.
+5. Integracja pluginu OpenCode z tym kontraktem.
+6. Test end-to-end w przykładowym projekcie.

package/kanban.js

@@ -3,6 +3,10 @@ const path = require('path');
 
 const BACKLOG = path.join(process.cwd(), 'backlog');
 const COLS = ['active', 'planned', 'icebox', 'done'];
+const GUI_PORT_FILE = '.kanbango-gui.json';
+const GUI_PORT_MIN = 5510;
+const GUI_PORT_MAX = 5999;
+const GUI_PORT_SPAN = GUI_PORT_MAX - GUI_PORT_MIN + 1;
 const STATUS_MAP = {
   active: 'in_progress',
   planned: 'planned',
@@ -10,9 +14,9 @@ const STATUS_MAP = {
   done: 'done'
 };
 const VIEW_FIELDS = {
-  summary: ['id', 'title', 'column', 'epic_group', 'created', 'progress'],
+  summary: ['task_number', 'title', 'column', 'epic_group', 'created', 'progress'],
   planning: [
-    'id',
+    'task_number',
     'title',
     'column',
     'epic_group',
@@ -20,11 +24,13 @@ const VIEW_FIELDS = {
     'progress',
     'description',
     'specs',
+    'in_scope',
+    'out_of_scope',
     'acceptance_criteria',
     'test_cases'
   ],
   execution: [
-    'id',
+    'task_number',
     'title',
     'column',
     'epic_group',
@@ -32,12 +38,14 @@ const VIEW_FIELDS = {
     'progress',
     'description',
     'specs',
+    'in_scope',
+    'out_of_scope',
     'acceptance_criteria',
     'test_cases',
     'subtasks'
   ],
   full: [
-    'id',
+    'task_number',
     'title',
     'column',
     'epic_group',
@@ -45,6 +53,8 @@ const VIEW_FIELDS = {
     'progress',
     'description',
     'specs',
+    'in_scope',
+    'out_of_scope',
     'acceptance_criteria',
     'test_cases',
     'subtasks',
@@ -52,6 +62,16 @@ const VIEW_FIELDS = {
   ]
 };
 
+// Hard-required on create: title only (keeps GUI/CLI quick-add usable).
+// Strongly recommended for agent/planned work — missing ones yield warnings, not errors.
+const RECOMMENDED_CREATE_FIELDS = [
+  'description',
+  'specs',
+  'in_scope',
+  'out_of_scope',
+  'acceptance_criteria'
+];
+
 function createKanbanError(code, message, hint, details = {}, retryable = false, status = 400) {
   const error = new Error(message);
   error.code = code;
@@ -74,6 +94,11 @@ function normalizeString(value, fallback = '') {
   return typeof value === 'string' ? value.trim() : fallback;
 }
 
+function extractTaskNumber(taskId) {
+  const match = normalizeString(taskId).match(/^(?:[A-Z]+-)?(\d+)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
 function normalizeStringArray(value) {
   if (!Array.isArray(value)) return [];
   return value
@@ -81,6 +106,36 @@ function normalizeStringArray(value) {
     .filter(Boolean);
 }
 
+function isPresentCreateField(field, value) {
+  if (field === 'description' || field === 'specs' || field === 'notes') {
+    return Boolean(normalizeString(value));
+  }
+  if (
+    field === 'in_scope' ||
+    field === 'out_of_scope' ||
+    field === 'acceptance_criteria' ||
+    field === 'test_cases' ||
+    field === 'subtasks'
+  ) {
+    if (field === 'subtasks') return normalizeSubtasks(value).length > 0;
+    return normalizeStringArray(value).length > 0;
+  }
+  return value !== undefined && value !== null && value !== '';
+}
+
+function missingRecommendedCreateFields(payload = {}) {
+  return RECOMMENDED_CREATE_FIELDS.filter((field) => !isPresentCreateField(field, payload[field]));
+}
+
+function createFieldWarnings(payload = {}) {
+  const missing = missingRecommendedCreateFields(payload);
+  if (missing.length === 0) return [];
+  return [
+    `Strongly recommended fields missing: ${missing.join(', ')}. ` +
+      'Fill them on create (or via update) so scope and done-criteria are explicit.'
+  ];
+}
+
 function normalizeSubtasks(value) {
   if (!Array.isArray(value)) return [];
   return value.map((subtask, idx) => ({
@@ -91,34 +146,48 @@ function normalizeSubtasks(value) {
   })).filter((subtask) => subtask.text);
 }
 
-function withLegacyTaskAlias(task) {
+function normalizeEvidence(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => ({
+    diff: normalizeString(item && item.diff),
+    test_command: normalizeString(item && item.test_command),
+    stdout: normalizeString(item && item.stdout),
+    stderr: normalizeString(item && item.stderr),
+    exit_code: Number.isInteger(item && item.exit_code) ? item.exit_code : null,
+    created: normalizeString(item && item.created) || todayIso()
+  }));
+}
+
+function normalizePlan(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
   return {
-    ...task,
-    tasks: task.subtasks.map((subtask) => ({
-      id: subtask.id,
-      text: subtask.text,
-      done: subtask.done,
-      description: subtask.description
-    }))
+    runner: value.runner && typeof value.runner === 'object' ? value.runner : null,
+    status: ['active', 'done'].includes(value.status) ? value.status : 'active'
   };
 }
 
 function normalizeTask(task) {
+  const id = normalizeString(task.id);
   const normalized = {
-    id: normalizeString(task.id),
-    title: stripTitlePrefix(task.title || task.id),
+    id,
+    title: stripTitlePrefix(task.title || id),
     column: COLS.includes(task.column) ? task.column : 'planned',
     epic_group: normalizeString(task.epic_group, '—') || '—',
     created: normalizeString(task.created) || todayIso(),
     description: normalizeString(task.description),
     specs: normalizeString(task.specs),
+    in_scope: normalizeStringArray(task.in_scope),
+    out_of_scope: normalizeStringArray(task.out_of_scope),
     acceptance_criteria: normalizeStringArray(task.acceptance_criteria),
     test_cases: normalizeStringArray(task.test_cases),
-    subtasks: normalizeSubtasks(task.subtasks || task.tasks),
-    notes: normalizeString(task.notes)
+    subtasks: normalizeSubtasks(task.subtasks),
+    notes: normalizeString(task.notes),
+    plan: normalizePlan(task.plan),
+    evidence: normalizeEvidence(task.evidence),
+    task_number: extractTaskNumber(id)
   };
 
-  return withLegacyTaskAlias(normalized);
+  return normalized;
 }
 
 function serializeTask(task) {
@@ -131,10 +200,15 @@ function serializeTask(task) {
     created: normalized.created,
     description: normalized.description,
     specs: normalized.specs,
+    in_scope: normalized.in_scope,
+    out_of_scope: normalized.out_of_scope,
     acceptance_criteria: normalized.acceptance_criteria,
     test_cases: normalized.test_cases,
     subtasks: normalized.subtasks,
-    notes: normalized.notes
+    notes: normalized.notes,
+    plan: normalized.plan,
+    evidence: normalized.evidence,
+    task_number: normalized.task_number
   };
 }
 
@@ -152,10 +226,6 @@ function pickFields(task, fieldNames) {
       picked.progress = getProgress(task);
       continue;
     }
-    if (field === 'tasks') {
-      picked.tasks = task.tasks;
-      continue;
-    }
     if (field in task) {
       picked[field] = task[field];
     }
@@ -231,6 +301,8 @@ async function parseMarkdownTask(filePath, column) {
     created: createdMatch ? createdMatch[1].trim() : todayIso(),
     description: extractSection(text, ['Opis', 'Description']),
     specs: extractSection(text, ['Specs', 'Specyfikacja']),
+    in_scope: parseListSection(extractSection(text, ['In Scope', 'W Zakresie'])),
+    out_of_scope: parseListSection(extractSection(text, ['Out of Scope', 'Poza Zakresem'])),
     acceptance_criteria: parseListSection(extractSection(text, ['Acceptance Criteria', 'Kryteria Akceptacji'])),
     test_cases: parseListSection(extractSection(text, ['Test Cases', 'Przypadki Testowe'])),
     subtasks,
@@ -323,7 +395,8 @@ async function findFile(epicId) {
 }
 
 async function getTask(taskId) {
-  const filePath = await findFile(taskId);
+  const resolvedId = await resolveTaskId(taskId);
+  const filePath = await findFile(resolvedId);
   if (!filePath) {
     throw createKanbanError(
       'TASK_NOT_FOUND',
@@ -339,6 +412,34 @@ async function getTask(taskId) {
   return parseEpic(filePath, column);
 }
 
+async function resolveTaskId(input) {
+  if (!input) return null;
+
+  const exact = await findFile(String(input));
+  if (exact) return String(input);
+
+  const num = parseInt(String(input), 10);
+  if (!Number.isFinite(num)) return null;
+
+  for (const col of COLS) {
+    const colDir = path.join(BACKLOG, col);
+    try {
+      const files = await fs.readdir(colDir);
+      const rawPattern = new RegExp(`^(?:[A-Z]+-)?${String(num)}(?:-|$)`);
+      const paddedPattern = new RegExp(`^(?:[A-Z]+-)?${String(num).padStart(3, '0')}(?:-|$)`);
+      const match = files.find((file) => {
+        const base = path.basename(file, path.extname(file));
+        return rawPattern.test(base) || paddedPattern.test(base + '-');
+      });
+      if (match) return path.basename(match, path.extname(match));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+
+  return String(input);
+}
+
 async function writeTask(task, previousFilePath = null) {
   const normalized = normalizeTask(task);
   await ensureBacklogDir();
@@ -403,7 +504,7 @@ async function migrateAll(options = {}) {
   return { migrated, errors };
 }
 
-async function nextPiNumber() {
+async function nextTaskNumber() {
   const ids = [];
 
   for (const col of COLS) {
@@ -411,7 +512,7 @@ async function nextPiNumber() {
     try {
       const files = await fs.readdir(colDir);
       for (const file of files) {
-        const match = file.match(/^PI-(\d+)/);
+        const match = file.match(/^(?:[A-Z]+-)?(\d+)/);
         if (match) ids.push(parseInt(match[1], 10));
       }
     } catch (error) {
@@ -462,24 +563,28 @@ async function doCreate(title, column = 'planned', epicGroup = '—', extra = {}
 
   validateColumn(column, 'col');
 
-  const nextId = await nextPiNumber();
+  const nextId = await nextTaskNumber();
   const slug = title
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .substring(0, 25);
   const task = normalizeTask({
-    id: `PI-${String(nextId).padStart(3, '0')}-${slug || 'task'}`,
+    id: String(nextId).padStart(3, '0'),
     title,
     column,
     epic_group: epicGroup || '—',
     created: todayIso(),
     description: extra.description,
     specs: extra.specs,
+    in_scope: extra.in_scope,
+    out_of_scope: extra.out_of_scope,
     acceptance_criteria: extra.acceptance_criteria,
     test_cases: extra.test_cases,
     subtasks: extra.subtasks,
-    notes: extra.notes
+    notes: extra.notes,
+    plan: extra.plan,
+    evidence: extra.evidence
   });
 
   return writeTask(task);
@@ -488,7 +593,8 @@ async function doCreate(title, column = 'planned', epicGroup = '—', extra = {}
 async function updateTask(taskId, patch) {
   validatePatch(patch);
 
-  const previousFilePath = await findFile(taskId);
+  const resolvedId = await resolveTaskId(taskId);
+  const previousFilePath = await findFile(resolvedId);
   if (!previousFilePath) {
     throw createKanbanError(
       'TASK_NOT_FOUND',
@@ -524,6 +630,32 @@ async function updateTask(taskId, patch) {
   if (patch.epic_group !== undefined) next.epic_group = normalizeString(patch.epic_group, '—') || '—';
   if (patch.description !== undefined) next.description = normalizeString(patch.description);
   if (patch.specs !== undefined) next.specs = normalizeString(patch.specs);
+  if (patch.in_scope !== undefined) {
+    if (!Array.isArray(patch.in_scope)) {
+      throw createKanbanError(
+        'VALIDATION_ERROR',
+        'in_scope must be an array of strings',
+        'Send in_scope as an array',
+        { field: 'in_scope' },
+        false,
+        400
+      );
+    }
+    next.in_scope = patch.in_scope;
+  }
+  if (patch.out_of_scope !== undefined) {
+    if (!Array.isArray(patch.out_of_scope)) {
+      throw createKanbanError(
+        'VALIDATION_ERROR',
+        'out_of_scope must be an array of strings',
+        'Send out_of_scope as an array',
+        { field: 'out_of_scope' },
+        false,
+        400
+      );
+    }
+    next.out_of_scope = patch.out_of_scope;
+  }
   if (patch.acceptance_criteria !== undefined) {
     if (!Array.isArray(patch.acceptance_criteria)) {
       throw createKanbanError(
@@ -550,9 +682,8 @@ async function updateTask(taskId, patch) {
     }
     next.test_cases = patch.test_cases;
   }
-  if (patch.subtasks !== undefined || patch.tasks !== undefined) {
-    const subtasks = patch.subtasks !== undefined ? patch.subtasks : patch.tasks;
-    if (!Array.isArray(subtasks)) {
+  if (patch.subtasks !== undefined) {
+    if (!Array.isArray(patch.subtasks)) {
       throw createKanbanError(
         'VALIDATION_ERROR',
         'subtasks must be an array',
@@ -562,9 +693,23 @@ async function updateTask(taskId, patch) {
         400
       );
     }
-    next.subtasks = subtasks;
+    next.subtasks = patch.subtasks;
   }
   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)) {
+      throw createKanbanError(
+        'VALIDATION_ERROR',
+        'evidence must be an array',
+        'Send evidence as an array of evidence objects',
+        { field: 'evidence' },
+        false,
+        400
+      );
+    }
+    next.evidence = patch.evidence;
+  }
 
   return writeTask(next, previousFilePath);
 }
@@ -624,6 +769,118 @@ async function doUpdate(epicId, newTitle, newTasks) {
   }
 }
 
+function guiPortFilePath() {
+  return path.join(BACKLOG, GUI_PORT_FILE);
+}
+
+function hashCwdToPort(cwd = process.cwd()) {
+  let hash = 0;
+  const input = String(cwd);
+  for (let i = 0; i < input.length; i++) {
+    hash = ((hash << 5) - hash + input.charCodeAt(i)) | 0;
+  }
+  return GUI_PORT_MIN + (Math.abs(hash) % GUI_PORT_SPAN);
+}
+
+function normalizeGuiPort(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
+    return null;
+  }
+  return parsed;
+}
+
+function resolvePreferredGuiPort(explicitPort) {
+  if (explicitPort !== undefined && explicitPort !== null && explicitPort !== '') {
+    const fromArg = normalizeGuiPort(explicitPort);
+    if (fromArg) return fromArg;
+  }
+
+  const fromEnv = normalizeGuiPort(process.env.KANBANGO_GUI_PORT);
+  if (fromEnv) return fromEnv;
+
+  return hashCwdToPort(process.cwd());
+}
+
+function isPidAlive(pid) {
+  const n = Number.parseInt(pid, 10);
+  if (!Number.isFinite(n) || n <= 0) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeGuiPortFile({ port, pid = process.pid } = {}) {
+  const normalizedPort = normalizeGuiPort(port);
+  if (!normalizedPort) {
+    throw createKanbanError(
+      'VALIDATION_ERROR',
+      'Invalid GUI port',
+      'Use an integer between 1 and 65535',
+      { port },
+      false,
+      400
+    );
+  }
+
+  await ensureBacklogDir();
+  const data = {
+    port: normalizedPort,
+    pid,
+    url: `http://localhost:${normalizedPort}`,
+    cwd: process.cwd(),
+    started_at: new Date().toISOString()
+  };
+  await fs.writeFile(guiPortFilePath(), JSON.stringify(data, null, 2), 'utf-8');
+  return data;
+}
+
+async function readGuiPortFile() {
+  try {
+    const raw = await fs.readFile(guiPortFilePath(), 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data || !normalizeGuiPort(data.port)) return null;
+    return data;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    return null;
+  }
+}
+
+async function clearGuiPortFile({ pid, force = false } = {}) {
+  const info = await readGuiPortFile();
+  if (!info) return false;
+  if (!force && pid !== undefined && info.pid !== pid) return false;
+  if (!force && pid === undefined && info.pid !== process.pid) return false;
+
+  try {
+    await fs.unlink(guiPortFilePath());
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function discoverRunningGui() {
+  const info = await readGuiPortFile();
+  if (!info || !isPidAlive(info.pid)) {
+    if (info) await clearGuiPortFile({ force: true });
+    return null;
+  }
+  return {
+    status: 'running',
+    port: info.port,
+    pid: info.pid,
+    url: info.url || `http://localhost:${info.port}`,
+    cwd: info.cwd,
+    started_at: info.started_at
+  };
+}
+
 module.exports = {
   ensureBacklogDir,
   parseEpic,
@@ -638,8 +895,23 @@ module.exports = {
   doUpdate,
   doCreate,
   createKanbanError,
+  createFieldWarnings,
+  missingRecommendedCreateFields,
   getProgress,
+  resolveTaskId,
+  hashCwdToPort,
+  normalizeGuiPort,
+  resolvePreferredGuiPort,
+  isPidAlive,
+  writeGuiPortFile,
+  readGuiPortFile,
+  clearGuiPortFile,
+  discoverRunningGui,
+  guiPortFilePath,
   COLS,
   STATUS_MAP,
-  VIEW_FIELDS
+  VIEW_FIELDS,
+  RECOMMENDED_CREATE_FIELDS,
+  GUI_PORT_MIN,
+  GUI_PORT_MAX
 };