kanbango 3.6.2 → 5.1.0

package/kanbango.md

@@ -1,48 +0,0 @@
-# kanbango — Rename + Migrate Tool Plan
-
-## Phase 1 — Add `migrate` command to `kanban.js`
-
-**New exported function `migrateAll(options)`** in `kanban.js`:
-- Walks all 4 columns
-- Finds `.md` files, reads via existing `parseMarkdownTask`, writes `.json` via `writeTask`
-- `writeTask` already deletes the old `.md` file automatically
-- `options.dryRun` — preview only, returns what would migrate
-- Returns `{ migrated: [{id, from, to}], errors: [{file, reason}] }`
-
-## Phase 2 — Add `kanban migrate` CLI subcommand
-
-In `bin/kanban.js`:
-- `kanban migrate` — runs migration, reports each file converted
-- `kanban migrate --dry-run` — preview only
-
-## Phase 3 — Rename everything from `markdown-kanban` → `kanbango`
-
-**Files to update:**
-
-| File | Changes |
-|------|---------|
-| `package.json` | name → `kanbango`, description → "JSON-first local Kanban board with web GUI, CLI, and MCP server", repo/homepage/bugs URLs → `k0r81/kanbango` |
-| `CHANGELOG.md` | Add `[2.0.0]` entry, rename references |
-| `bin/kanban.js` | `claudeMcpConfig` and `openCodeMcpConfig` — change `npx markdown-kanban` → `npx kanbango` (lines 26, 42) |
-| `README.md` | All `markdown-kanban` → `kanbango`, update description |
-| `LLM_AGENTS.md` | Same renames |
-| `AGENTS.md` | Same renames |
-| `.npmignore` | Check if any path references need updating |
-
-**What stays the same:**
-- CLI binary names: `kanban` and `kanban-cmd` — no change
-- `backlog/` directory structure
-- All internal logic in `kanban.js`, `mcp-server.js`, `index.js`
-
-## Phase 4 — Tag & Publish
-
-1. Bump version to `2.0.0` in `package.json`
-2. `git tag v2.0.0 -m "kanbango: rename + migrate tool"`
-3. Push tag to GitHub
-4. Rename GitHub repo `k0r81/markdown-kanban` → `k0r81/kanbango` (manual, via GitHub UI)
-5. `npm publish` — first publish as `kanbango`
-
-## Phase 5 — Verify
-
-- `npm search kanbango` to confirm it's live
-- Check download page at `https://www.npmjs.com/package/kanbango`

package/planv2.md

@@ -1,317 +0,0 @@
-# Plan V2
-
-## Goal
-
-Evolve `markdown-kanban` into an LLM-first task system with:
-
-- rich task and subtask descriptions
-- minimal token usage in MCP flows
-- a minimal MCP surface area
-- structured, actionable error messages
-- partial reads so agents only fetch the task slices they need
-
-## Core Decision
-
-Use JSON as the canonical task storage format.
-
-Reasoning:
-
-- Markdown is human-friendly, but becomes fragile once tasks need nested rich fields.
-- JSON is easier to validate, partially read, partially update, and return through MCP.
-- Token savings will come primarily from response shaping in MCP, not from the on-disk format itself.
-
-## Token Strategy
-
-The main token optimization should happen in MCP responses, not by compressing field names or over-optimizing file syntax.
-
-Avoid:
-
-- always returning the full task
-- adding many narrow MCP methods
-- cryptic short keys like `sp`, `ac`, `d`
-
-Prefer:
-
-- one read tool with multiple views
-- explicit field selection
-- compact summary responses by default
-- structured update responses with configurable return payloads
-
-## Recommended Task Schema
-
-```json
-{
-  "id": "014",
-  "title": "Google Calendar Integration",
-  "column": "active",
-  "epic_group": "Phase 1",
-  "created": "2026-07-07",
-  "description": "High-level context and implementation plan in markdown.",
-  "specs": "Technical constraints, APIs, data model, edge cases.",
-  "in_scope": [
-    "OAuth connect/disconnect",
-    "Two-way event sync"
-  ],
-  "out_of_scope": [
-    "Microsoft Calendar",
-    "Mobile push notifications"
-  ],
-  "acceptance_criteria": [
-    "User can connect Google account",
-    "Events sync in both directions",
-    "Sync conflicts are logged"
-  ],
-  "subtasks": [
-    {
-      "id": "st-1",
-      "text": "Implement OAuth flow",
-      "done": false,
-      "description": "Use PKCE, store refresh token encrypted."
-    }
-  ],
-  "notes": "Optional freeform notes"
-}
-```
-
-## Field Semantics
-
-- `description`: the main context, why the work exists, and the implementation plan
-- `specs`: concrete technical facts, constraints, APIs, data shape, edge cases
-- `in_scope`: what this task includes (boundaries)
-- `out_of_scope`: explicit non-goals / exclusions
-- `acceptance_criteria`: what must be true for the task to count as done
-- `subtasks[].description`: local execution detail for a subtask
-- `notes`: optional freeform leftovers, references, or observations
-
-This split is useful for both humans and agents.
-
-## MCP Surface
-
-Keep the MCP surface at 3 tools:
-
-- `kanban_read`
-- `kanban_create`
-- `kanban_update`
-
-Do not add separate tools like:
-
-- `kanban_read_specs`
-- `kanban_read_ac`
-- `kanban_read_subtasks`
-
-That would increase surface area without meaningfully reducing tokens.
-
-## kanban_read Design
-
-Add support for response shaping.
-
-### Option A: view presets
-
-```json
-{
-  "operation": "show",
-  "task_id": "014",
-  "view": "planning"
-}
-```
-
-Suggested views:
-
-- `summary`: id, title, column, epic, created, progress counts
-- `planning`: summary + description + specs + in_scope + out_of_scope + acceptance_criteria
-- `execution`: planning + subtasks
-- `full`: everything including notes and metadata
-
-### Option B: explicit fields
-
-```json
-{
-  "operation": "show",
-  "task_id": "014",
-  "fields": ["title", "description", "acceptance_criteria"]
-}
-```
-
-Recommendation: support both.
-
-- `view` is simple and ergonomic
-- `fields` is precise for advanced agents
-
-If both are supplied, `fields` should win.
-
-## kanban_create Design
-
-Allow rich fields during creation, but keep minimal creation possible.
-
-Minimal create:
-
-```json
-{
-  "title": "Add user authentication"
-}
-```
-
-Full create:
-
-```json
-{
-  "title": "Add user authentication",
-  "col": "planned",
-  "epic": "Auth",
-  "description": "Implement auth flow and session model.",
-  "specs": "Use OAuth + session cookies.",
-  "acceptance_criteria": [
-    "User can sign in",
-    "Session persists after refresh"
-  ],
-  "subtasks": [
-    {
-      "text": "Create auth routes",
-      "description": "Add login and callback handlers."
-    }
-  ],
-  "notes": "Optional"
-}
-```
-
-## kanban_update Design
-
-Use a patch-like payload and let callers control the returned payload size.
-
-```json
-{
-  "operation": "update",
-  "task_id": "014",
-  "patch": {
-    "description": "Updated implementation plan...",
-    "acceptance_criteria": [
-      "OAuth works",
-      "Tokens refresh correctly"
-    ]
-  },
-  "return": "summary"
-}
-```
-
-Suggested `return` values:
-
-- `none`
-- `summary`
-- `full`
-
-Default should be `summary`, not `full`.
-
-This avoids sending large descriptions back after every small edit.
-
-## Read Strategy For Agents
-
-Agents should not always read the whole task.
-
-Recommended workflows:
-
-### Triage
-
-Use `summary` only.
-
-### Planning
-
-Read:
-
-- `description`
-- `specs`
-- `acceptance_criteria`
-
-### Implementation
-
-Read:
-
-- planning fields
-- subtasks
-
-### Verification
-
-Read:
-
-- `acceptance_criteria`
-- progress / status fields
-
-### Backlog cleanup
-
-Read:
-
-- summary only
-
-This is not a bad idea. It is the correct way to reduce token use while staying useful.
-
-## Error Design
-
-Errors should be structured JSON, not a plain string.
-
-Recommended shape:
-
-```json
-{
-  "error": {
-    "code": "TASK_NOT_FOUND",
-    "message": "Task 014 was not found",
-    "hint": "Call kanban_read with operation=list to discover valid task ids",
-    "details": {
-      "task_id": "014"
-    },
-    "retryable": false
-  }
-}
-```
-
-Suggested error codes:
-
-- `TASK_NOT_FOUND`
-- `INVALID_COLUMN`
-- `INVALID_SUBTASK_INDEX`
-- `VALIDATION_ERROR`
-- `MISSING_REQUIRED_FIELD`
-- `TASK_CONFLICT`
-- `PARSE_ERROR`
-
-Good errors should help an agent recover without extra back-and-forth.
-
-## Migration Strategy
-
-Existing Markdown files are already persisted data, so backward compatibility matters during migration.
-
-Recommended migration plan:
-
-1. Add JSON schema support.
-2. Support reading both `.md` and `.json` task files during transition.
-3. Write new tasks as JSON.
-4. Add an optional migration command later if needed.
-5. Once the repo is clean and the migration is accepted, decide whether to keep Markdown read support permanently.
-
-## Suggested Defaults
-
-- Canonical storage: JSON
-- MCP tools: keep exactly 3
-- Default read view: `summary` for lists, `planning` or `summary` for show depending on client choice
-- Default update return payload: `summary`
-- Rich task fields: `description`, `specs`, `acceptance_criteria`, `notes`
-- Rich subtask fields: `text`, `done`, `description`
-
-## Non-Goals
-
-Avoid for now:
-
-- many specialized MCP methods
-- abbreviated schema keys just to save a few tokens
-- always rendering HTML for descriptions
-- over-structuring subtasks with too many fields
-
-## Next Implementation Steps
-
-1. Define the JSON schema in code and docs.
-2. Update `kanban.js` to read and write JSON tasks.
-3. Add transitional support for reading existing Markdown tasks.
-4. Extend `kanban_read` with `view` and `fields`.
-5. Extend `kanban_create` and `kanban_update` with rich fields and `patch` semantics.
-6. Add structured MCP error responses with codes and hints.
-7. Update the web GUI to edit `description`, `specs`, `acceptance_criteria`, and subtask descriptions.
-8. Add tests for partial reads, structured errors, and Markdown-to-JSON compatibility.

package/tests/fixtures/fake-opencode.js

@@ -1,69 +0,0 @@
-#!/usr/bin/env node
-/**
- * Fake opencode runner for workflow-gates tests.
- * Env:
- *   FAKE_OPENCODE_MODE = pass|fail|blocked|gate_pass|gate_fail|gate_missing|hang|exit1
- *   FAKE_OPENCODE_REVIEW_MODE = gate_pass|gate_fail|gate_missing (optional; overrides when --agent is review)
- *   FAKE_OPENCODE_ARGV_FILE = path to write JSON argv
- *   FAKE_OPENCODE_HANG_MS = hang duration (default 60000)
- */
-const fs = require('fs');
-const path = require('path');
-
-const args = process.argv.slice(2);
-const agentIdx = args.indexOf('--agent');
-const agent = agentIdx >= 0 ? args[agentIdx + 1] : '';
-
-let mode = String(process.env.FAKE_OPENCODE_MODE || 'pass').trim();
-const reviewMode = String(process.env.FAKE_OPENCODE_REVIEW_MODE || '').trim();
-// Review agents: prefer review mode, else map testing modes to gate_* defaults.
-if (agent === 'temida' || agent === 'review' || /temida|review/i.test(agent)) {
-  if (reviewMode) {
-    mode = reviewMode;
-  } else if (mode === 'pass') {
-    mode = 'gate_pass';
-  } else if (mode === 'fail') {
-    mode = 'gate_fail';
-  } else if (mode === 'blocked' || mode === 'gate_missing') {
-    mode = mode === 'blocked' ? 'gate_missing' : mode;
-  }
-}
-
-const argvFile = process.env.FAKE_OPENCODE_ARGV_FILE;
-if (argvFile) {
-  try {
-    fs.mkdirSync(path.dirname(argvFile), { recursive: true });
-    fs.writeFileSync(argvFile, JSON.stringify(args, null, 2) + '\n', 'utf-8');
-  } catch (err) {
-    process.stderr.write(`argv write failed: ${err.message}\n`);
-  }
-}
-
-if (mode === 'hang') {
-  const ms = Number(process.env.FAKE_OPENCODE_HANG_MS || 60000);
-  setTimeout(() => process.exit(0), ms);
-  return;
-}
-
-const outputs = {
-  pass: { out: 'Tests green\nPASS\n', code: 0 },
-  fail: { out: 'Tests red\nFAIL\n', code: 1 },
-  blocked: { out: 'Missing env\nBLOCKED\n', code: 0 },
-  gate_pass: {
-    out: 'Nagroda: solidny diff.\nKara kosmetyczna: naming.\nWedka: ok.\nGATE: PASS\n',
-    code: 0
-  },
-  gate_fail: {
-    out: 'Kara: brak testow produkcji.\nWedka: dodaj testy.\nGATE: FAIL\n',
-    code: 0
-  },
-  gate_missing: {
-    out: 'Wyrok bez markera bramki.\nTylko narracja.\n',
-    code: 0
-  },
-  exit1: { out: 'crashed without verdict\n', code: 1 }
-};
-
-const picked = outputs[mode] || outputs.pass;
-process.stdout.write(picked.out);
-process.exit(picked.code);

package/tests/index.js

@@ -1,19 +0,0 @@
-const assert = require('assert');
-const path = require('path');
-
-function run() {
-  const pkg = require(path.join(__dirname, '..', 'index.js'));
-  assert.ok(pkg.kanban, 'index exports kanban');
-  assert.ok(pkg.plan, 'index exports plan');
-  assert.ok(pkg.workflow, 'index exports workflow');
-  assert.ok(pkg.guiRegistry, 'index exports guiRegistry');
-  assert.ok(pkg.playbook, 'index exports playbook');
-  assert.ok(pkg.kanban.COLS.includes('testing'));
-  assert.ok(pkg.kanban.COLS.includes('review'));
-  assert.strictEqual(typeof pkg.workflow.loadConfig, 'function');
-  assert.strictEqual(typeof pkg.workflow.maybeEnqueueOnColumnEnter, 'function');
-  assert.strictEqual(typeof pkg.plan.done, 'function');
-  console.log('✓ index.test.js passed');
-}
-
-run();

package/tests/kanban-cli.js

@@ -1,118 +0,0 @@
-const assert = require('assert');
-const crypto = require('crypto');
-const fs = require('fs').promises;
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-const PKG = path.join(__dirname, '..');
-const CLI = path.join(PKG, 'bin', 'kanban.js');
-const SRC_QA = path.join(PKG, 'agents', 'qa-tester.md');
-
-function runCli(cwd, args) {
-  return spawnSync(process.execPath, [CLI, ...args], {
-    cwd,
-    encoding: 'utf-8'
-  });
-}
-
-function sha256(content) {
-  return crypto.createHash('sha256').update(content).digest('hex');
-}
-
-async function run() {
-  // init creates testing/review dirs + README
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'kanbango-bin-'));
-  const init = runCli(root, ['init']);
-  assert.strictEqual(init.status, 0, init.stderr);
-  for (const col of ['testing', 'review', 'active', 'planned', 'icebox', 'done']) {
-    const st = await fs.stat(path.join(root, 'backlog', col));
-    assert.ok(st.isDirectory(), col);
-  }
-  const readme = await fs.readFile(path.join(root, 'backlog', 'README.md'), 'utf-8');
-  assert.ok(readme.includes('testing/'));
-  assert.ok(readme.includes('review/'));
-
-  // mcp-init --opencode copies agents + writes manifest
-  const ocRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kanbango-bin-oc-'));
-  const oc = runCli(ocRoot, ['mcp-init', '--opencode']);
-  assert.strictEqual(oc.status, 0, oc.stderr);
-  const agentDir = path.join(ocRoot, '.opencode', 'agent');
-  const agents = await fs.readdir(agentDir);
-  assert.ok(agents.includes('qa-tester.md'));
-  assert.ok(agents.includes('temida.md'));
-  assert.ok(agents.includes('.kanbango-agents.json'));
-  const temida = await fs.readFile(path.join(agentDir, 'temida.md'), 'utf-8');
-  assert.ok(temida.includes('GATE: PASS'));
-
-  const srcQa = await fs.readFile(SRC_QA, 'utf-8');
-  const srcHash = sha256(srcQa);
-  const manifest1 = JSON.parse(await fs.readFile(path.join(agentDir, '.kanbango-agents.json'), 'utf-8'));
-  assert.strictEqual(manifest1.agents['qa-tester.md'], srcHash);
-
-  // second run, identical source → unchanged
-  const againSame = runCli(ocRoot, ['mcp-init', '--opencode']);
-  assert.strictEqual(againSame.status, 0);
-  assert.ok(againSame.stdout.includes('Bez zmian') || againSame.stdout.includes('unchanged')
-    || againSame.stdout.includes('Pominięto') === false);
-  assert.ok(againSame.stdout.includes('Bez zmian .opencode/agent/qa-tester.md'));
-  assert.strictEqual(await fs.readFile(path.join(agentDir, 'qa-tester.md'), 'utf-8'), srcQa);
-
-  // local edit while manifest matches previous package hash → conflict, keep local
-  await fs.writeFile(path.join(agentDir, 'qa-tester.md'), 'KEEP_LOCAL_EDIT', 'utf-8');
-  const conflictRun = runCli(ocRoot, ['mcp-init', '--opencode']);
-  assert.strictEqual(conflictRun.status, 0);
-  assert.ok(
-    conflictRun.stdout.includes('Konflikt') || conflictRun.stdout.includes('Pominięto'),
-    `expected conflict/skip message, got: ${conflictRun.stdout}`
-  );
-  assert.strictEqual(
-    await fs.readFile(path.join(agentDir, 'qa-tester.md'), 'utf-8'),
-    'KEEP_LOCAL_EDIT'
-  );
-
-  // clean older package version: dest matches recorded hash, source "new" → auto update
-  // Simulate by writing dest = old body, manifest hash = old hash, then force-path via
-  // restoring package content is fixed; instead write dest to old body with matching manifest.
-  const oldBody = 'OLD_PACKAGE_VERSION\n';
-  const oldHash = sha256(oldBody);
-  await fs.writeFile(path.join(agentDir, 'qa-tester.md'), oldBody, 'utf-8');
-  const man = JSON.parse(await fs.readFile(path.join(agentDir, '.kanbango-agents.json'), 'utf-8'));
-  man.agents['qa-tester.md'] = oldHash;
-  await fs.writeFile(
-    path.join(agentDir, '.kanbango-agents.json'),
-    JSON.stringify(man, null, 2) + '\n',
-    'utf-8'
-  );
-  const autoUpdate = runCli(ocRoot, ['mcp-init', '--opencode']);
-  assert.strictEqual(autoUpdate.status, 0, autoUpdate.stderr);
-  assert.ok(
-    autoUpdate.stdout.includes('Zaktualizowano .opencode/agent/qa-tester.md'),
-    autoUpdate.stdout
-  );
-  assert.strictEqual(await fs.readFile(path.join(agentDir, 'qa-tester.md'), 'utf-8'), srcQa);
-  const manAfter = JSON.parse(await fs.readFile(path.join(agentDir, '.kanbango-agents.json'), 'utf-8'));
-  assert.strictEqual(manAfter.agents['qa-tester.md'], srcHash);
-
-  // --force overwrites local edit
-  await fs.writeFile(path.join(agentDir, 'qa-tester.md'), 'FORCE_ME', 'utf-8');
-  const forceRun = runCli(ocRoot, ['mcp-init', '--opencode', '--force']);
-  assert.strictEqual(forceRun.status, 0);
-  assert.strictEqual(await fs.readFile(path.join(agentDir, 'qa-tester.md'), 'utf-8'), srcQa);
-
-  // --claude does not create .opencode/agent
-  const claudeRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kanbango-bin-cl-'));
-  const cl = runCli(claudeRoot, ['mcp-init', '--claude']);
-  assert.strictEqual(cl.status, 0, cl.stderr);
-  await assert.rejects(
-    () => fs.access(path.join(claudeRoot, '.opencode', 'agent')),
-    (err) => err.code === 'ENOENT'
-  );
-
-  console.log('✓ bin-kanban.test.js passed');
-}
-
-run().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});

package/tests/kanban.js

@@ -1,104 +0,0 @@
-const assert = require('assert');
-const fs = require('fs').promises;
-const os = require('os');
-const path = require('path');
-
-async function run() {
-  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kanbango-kanban-'));
-  process.chdir(tempRoot);
-  const kanban = require(path.join(__dirname, '..', 'kanban.js'));
-
-  assert.ok(kanban.COLS.includes('testing'));
-  assert.ok(kanban.COLS.includes('review'));
-  assert.strictEqual(kanban.STATUS_MAP.testing, 'testing');
-  assert.strictEqual(kanban.STATUS_MAP.review, 'review');
-
-  await kanban.ensureBacklogDir();
-  for (const col of ['testing', 'review']) {
-    const st = await fs.stat(path.join(tempRoot, 'backlog', col));
-    assert.ok(st.isDirectory());
-  }
-
-  const ev = kanban.normalizeEvidence([{
-    diff: 'old',
-    test_command: 't',
-    stdout: '',
-    stderr: '',
-    exit_code: 0,
-    stage: 'testing',
-    agent: 'qa-tester',
-    verdict: 'pass',
-    summary: 'ok'
-  }]);
-  assert.strictEqual(ev[0].stage, 'testing');
-  assert.strictEqual(ev[0].verdict, 'pass');
-
-  const wf = kanban.normalizeWorkflow({
-    stage: 'review',
-    status: 'running',
-    agent: 'temida',
-    run_id: 'run-x'
-  });
-  assert.strictEqual(wf.stage, 'review');
-  assert.strictEqual(wf.status, 'running');
-
-  const task = await kanban.doCreate('Kanban unit', 'active', '—', {});
-  const moved = await kanban.updateTask(task.id, { column: 'testing' });
-  assert.strictEqual(moved.column, 'testing');
-
-  await assert.rejects(
-    () => kanban.updateTask(task.id, { column: 'done' }),
-    (err) => {
-      assert.strictEqual(err.code, 'INVALID_TRANSITION');
-      assert.deepStrictEqual(err.details.allowed_columns, ['active', 'review']);
-      assert.strictEqual(err.details.from, 'testing');
-      assert.strictEqual(err.details.to, 'done');
-      assert.ok(err.hint.includes('active, review'));
-      return true;
-    }
-  );
-  assert.deepStrictEqual(kanban.allowedColumnsFrom('active'), ['planned', 'testing', 'icebox']);
-  assert.deepStrictEqual(kanban.allowedColumnsFrom('review'), ['active', 'done']);
-  kanban.validateTransition('active', 'testing', '001');
-  kanban.validateTransition('testing', 'testing', '001');
-
-  const appended = await kanban.updateTask(task.id, {
-    appendEvidence: {
-      diff: '',
-      test_command: 'fake',
-      stdout: 'PASS',
-      stderr: '',
-      exit_code: 0,
-      stage: 'testing',
-      agent: 'qa-tester',
-      verdict: 'pass',
-      summary: 'PASS'
-    },
-    workflow: {
-      stage: 'testing',
-      status: 'pass',
-      agent: 'qa-tester',
-      run_id: 'run-1'
-    }
-  });
-  assert.ok(appended.evidence.some((e) => e.verdict === 'pass'));
-  assert.strictEqual(appended.workflow.status, 'pass');
-
-  assert.strictEqual(
-    kanban.deriveEpicStatus([{ column: 'testing' }], {}),
-    'active'
-  );
-  const progress = kanban.getEpicProgress([
-    { column: 'testing' },
-    { column: 'review' }
-  ]);
-  assert.strictEqual(progress.tasks_testing, 1);
-  assert.strictEqual(progress.tasks_review, 1);
-
-  console.log('✓ kanban.test.js passed');
-}
-
-run().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});