@basementuniverse/kanbn 0.10.0 → 1.0.1

package/skills/kanbn-plan/scripts/check-dependency-cycles.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+
+function usage() {
+  console.error('Usage: node skills/kanbn-plan/scripts/check-dependency-cycles.mjs [project-root] [--json]');
+}
+
+function parseArgs(argv) {
+  let projectRoot = process.cwd();
+  let json = false;
+
+  for (const arg of argv) {
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      usage();
+      process.exit(1);
+    }
+
+    if (projectRoot !== process.cwd()) {
+      usage();
+      process.exit(1);
+    }
+
+    projectRoot = arg;
+  }
+
+  return {
+    json,
+    projectRoot: path.resolve(projectRoot)
+  };
+}
+
+function ensureKanbnFiles(projectRoot) {
+  const tasksPath = path.join(projectRoot, '.kanbn', 'tasks');
+  if (!fs.existsSync(tasksPath)) {
+    throw new Error(`No Kanbn tasks directory found at ${tasksPath}`);
+  }
+  return tasksPath;
+}
+
+function normaliseRelationType(type) {
+  return String(type || '').trim().toLowerCase();
+}
+
+function getTaskIdFromHref(href) {
+  const fileName = path.basename(String(href || '').trim());
+  return fileName.endsWith('.md') ? fileName.slice(0, -3) : fileName;
+}
+
+function extractRelationsSection(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const sectionLines = [];
+  let inSection = false;
+
+  for (const line of lines) {
+    if (/^##\s+Relations\s*$/.test(line.trim())) {
+      inSection = true;
+      continue;
+    }
+
+    if (inSection && /^##\s+/.test(line.trim())) {
+      break;
+    }
+
+    if (inSection) {
+      sectionLines.push(line);
+    }
+  }
+
+  return sectionLines.join('\n').trim();
+}
+
+function parseRelations(markdown) {
+  const section = extractRelationsSection(markdown);
+  if (!section) {
+    return [];
+  }
+
+  const relations = [];
+  const lines = section.split(/\r?\n/);
+  const relationPattern = /^-\s+\[([^\]]+)\]\(([^)]+)\)\s*$/;
+
+  for (const line of lines) {
+    const match = line.trim().match(relationPattern);
+    if (!match) {
+      continue;
+    }
+
+    const text = match[1].trim();
+    const href = match[2].trim();
+    const targetTaskId = getTaskIdFromHref(href);
+    const relationType = text.endsWith(targetTaskId)
+      ? text.slice(0, text.length - targetTaskId.length).trim()
+      : text;
+
+    relations.push({
+      task: targetTaskId,
+      type: normaliseRelationType(relationType)
+    });
+  }
+
+  return relations;
+}
+
+function loadTasks(tasksPath) {
+  const tasks = new Map();
+
+  for (const entry of fs.readdirSync(tasksPath, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) {
+      continue;
+    }
+
+    const taskId = entry.name.slice(0, -3);
+    const markdown = fs.readFileSync(path.join(tasksPath, entry.name), 'utf8');
+    tasks.set(taskId, {
+      id: taskId,
+      relations: parseRelations(markdown)
+    });
+  }
+
+  return tasks;
+}
+
+function buildDependencyGraph(tasks) {
+  const graph = new Map();
+  const danglingReferences = [];
+
+  for (const taskId of tasks.keys()) {
+    graph.set(taskId, new Set());
+  }
+
+  for (const [taskId, task] of tasks.entries()) {
+    for (const relation of task.relations) {
+      if (!relation.task) {
+        continue;
+      }
+
+      let fromId = null;
+      let toId = null;
+
+      if (relation.type === 'depends-on') {
+        fromId = relation.task;
+        toId = taskId;
+      } else if (relation.type === 'blocks') {
+        fromId = taskId;
+        toId = relation.task;
+      } else {
+        continue;
+      }
+
+      if (!tasks.has(fromId) || !tasks.has(toId)) {
+        danglingReferences.push({
+          from: taskId,
+          relationType: relation.type,
+          target: relation.task
+        });
+        continue;
+      }
+
+      graph.get(fromId).add(toId);
+    }
+  }
+
+  return { danglingReferences, graph };
+}
+
+function findCycles(graph) {
+  const visited = new Set();
+  const visiting = new Set();
+  const stack = [];
+  const cycles = [];
+  const seenCycleKeys = new Set();
+
+  function recordCycle(startNode) {
+    const startIndex = stack.indexOf(startNode);
+    if (startIndex === -1) {
+      return;
+    }
+
+    const cycle = stack.slice(startIndex).concat(startNode);
+    const uniqueNodes = cycle.slice(0, -1);
+    const canonicalStart = [...uniqueNodes].sort()[0];
+    const canonicalIndex = uniqueNodes.indexOf(canonicalStart);
+    const rotated = uniqueNodes.slice(canonicalIndex).concat(uniqueNodes.slice(0, canonicalIndex));
+    const cycleKey = rotated.join('>');
+
+    if (!seenCycleKeys.has(cycleKey)) {
+      seenCycleKeys.add(cycleKey);
+      cycles.push(rotated.concat(rotated[0]));
+    }
+  }
+
+  function visit(node) {
+    visited.add(node);
+    visiting.add(node);
+    stack.push(node);
+
+    for (const nextNode of graph.get(node) || []) {
+      if (!visited.has(nextNode)) {
+        visit(nextNode);
+      } else if (visiting.has(nextNode)) {
+        recordCycle(nextNode);
+      }
+    }
+
+    stack.pop();
+    visiting.delete(node);
+  }
+
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) {
+      visit(node);
+    }
+  }
+
+  return cycles;
+}
+
+function printTextReport(result) {
+  if (result.danglingReferences.length > 0) {
+    console.error(`Dangling dependency references: ${result.danglingReferences.length}`);
+    for (const reference of result.danglingReferences) {
+      console.error(`- ${reference.from}: ${reference.relationType} ${reference.target}`);
+    }
+  }
+
+  if (result.cycles.length > 0) {
+    console.error(`Dependency cycles detected: ${result.cycles.length}`);
+    for (const cycle of result.cycles) {
+      console.error(`- ${cycle.join(' -> ')}`);
+    }
+  }
+
+  if (result.danglingReferences.length === 0 && result.cycles.length === 0) {
+    console.log('No dependency cycles or dangling dependency references found');
+  }
+}
+
+function main() {
+  const { json, projectRoot } = parseArgs(process.argv.slice(2));
+
+  let tasksPath;
+  try {
+    tasksPath = ensureKanbnFiles(projectRoot);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  const tasks = loadTasks(tasksPath);
+  const { graph, danglingReferences } = buildDependencyGraph(tasks);
+  const cycles = findCycles(graph);
+  const result = { cycles, danglingReferences };
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printTextReport(result);
+  }
+
+  if (cycles.length > 0 || danglingReferences.length > 0) {
+    process.exit(1);
+  }
+}
+
+main();

package/skills/kanbn-plan/scripts/validate-kanbn.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+import { spawnSync } from 'child_process';
+
+function usage() {
+  console.error('Usage: node skills/kanbn-plan/scripts/validate-kanbn.mjs [project-root]');
+}
+
+function resolveProjectRoot(argv) {
+  if (argv.length > 1) {
+    usage();
+    process.exit(1);
+  }
+
+  return path.resolve(argv[0] || process.cwd());
+}
+
+function ensureKanbnFiles(projectRoot) {
+  const indexPath = path.join(projectRoot, '.kanbn', 'index.md');
+  const tasksPath = path.join(projectRoot, '.kanbn', 'tasks');
+
+  if (!fs.existsSync(indexPath)) {
+    console.error(`No Kanbn index found at ${indexPath}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(tasksPath)) {
+    console.error(`No Kanbn tasks directory found at ${tasksPath}`);
+    process.exit(1);
+  }
+}
+
+function getCandidates(projectRoot) {
+  const candidates = [];
+  const localBin = path.join(projectRoot, 'node_modules', '.bin', 'kanbn');
+
+  if (process.env.KANBN_BIN) {
+    candidates.push({ command: process.env.KANBN_BIN, args: [], label: process.env.KANBN_BIN });
+  }
+
+  if (fs.existsSync(localBin)) {
+    candidates.push({ command: localBin, args: [], label: localBin });
+  }
+
+  candidates.push({ command: 'kanbn', args: [], label: 'kanbn' });
+  candidates.push({ command: 'npx', args: ['-y', '@basementuniverse/kanbn'], label: 'npx -y @basementuniverse/kanbn' });
+
+  return candidates;
+}
+
+function runValidate(projectRoot) {
+  const candidates = getCandidates(projectRoot);
+  let lastError = null;
+
+  for (const candidate of candidates) {
+    const result = spawnSync(
+      candidate.command,
+      [...candidate.args, 'validate', '--json'],
+      {
+        cwd: projectRoot,
+        encoding: 'utf8'
+      }
+    );
+
+    if (result.error && result.error.code === 'ENOENT') {
+      lastError = result.error;
+      continue;
+    }
+
+    return { candidate, result };
+  }
+
+  throw lastError || new Error('Unable to locate a runnable Kanbn CLI');
+}
+
+function extractValidationErrors(output) {
+  const start = output.indexOf('[');
+  const end = output.lastIndexOf(']');
+
+  if (start === -1 || end === -1 || end < start) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(output.slice(start, end + 1));
+  } catch (error) {
+    return null;
+  }
+}
+
+function main() {
+  const projectRoot = resolveProjectRoot(process.argv.slice(2));
+  ensureKanbnFiles(projectRoot);
+
+  let execution;
+  try {
+    execution = runValidate(projectRoot);
+  } catch (error) {
+    console.error(`Unable to run Kanbn validation: ${error.message}`);
+    process.exit(1);
+  }
+
+  const { candidate, result } = execution;
+  const combinedOutput = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+
+  if (result.status === 0) {
+    if (combinedOutput) {
+      console.log(combinedOutput);
+    } else {
+      console.log(`Kanbn validation passed via ${candidate.label}`);
+    }
+    return;
+  }
+
+  const errors = extractValidationErrors(combinedOutput);
+  if (errors) {
+    console.error(`Kanbn validation reported ${errors.length} error(s) via ${candidate.label}:`);
+    for (const error of errors) {
+      if (error && typeof error === 'object') {
+        console.error(JSON.stringify(error, null, 2));
+      } else {
+        console.error(String(error));
+      }
+    }
+    process.exit(1);
+  }
+
+  console.error(combinedOutput || `Kanbn validation failed via ${candidate.label}`);
+  process.exit(result.status || 1);
+}
+
+main();

package/src/controller/add.js

@@ -23,6 +23,11 @@ async function interactiveCreateTask(taskData, taskIds, columnName, columnNames)
     'due' in taskData.metadata &&
     taskData.metadata.due != null
   );
+  const postponedDateExists = (
+    'metadata' in taskData &&
+    'postponed' in taskData.metadata &&
+    taskData.metadata.postponed != null
+  );
   const assignedExists = (
     'metadata' in taskData &&
     'assigned' in taskData.metadata &&
@@ -76,6 +81,21 @@ async function interactiveCreateTask(taskData, taskIds, columnName, columnNames)
       format: ['Y', '/', 'MM', '/', 'DD'],
       when: answers => answers.setDue,
     },
+    {
+      type: 'confirm',
+      name: 'setPostponed',
+      message: 'Set a postponed date?',
+      default: false,
+      when: answers => !postponedDateExists
+    },
+    {
+      type: 'datepicker',
+      name: 'postponed',
+      message: 'Postponed date:',
+      default: postponedDateExists ? taskData.metadata.postponed : new Date(),
+      format: ['Y', '/', 'MM', '/', 'DD'],
+      when: answers => answers.setPostponed,
+    },
     {
       type: 'confirm',
       name: 'setAssigned',
@@ -323,6 +343,15 @@ module.exports = async args => {
     }
   }
 
+  // Postponed date
+  if (args.postponed) {
+    taskData.metadata.postponed = chrono.parseDate(utility.strArg(args.postponed));
+    if (taskData.metadata.postponed === null) {
+      utility.error('Unable to parse postponed date');
+      return;
+    }
+  }
+
   // Progress
   if (args.progress) {
     const progressValue = parseFloat(utility.strArg(args.progress));
@@ -450,7 +479,10 @@ module.exports = async args => {
         taskData.description = answers.description;
       }
       if ('due' in answers) {
-        taskData.metadata.due = answers.due.toISOString();
+        taskData.metadata.due = answers.due;
+      }
+      if ('postponed' in answers) {
+        taskData.metadata.postponed = answers.postponed;
       }
       if ('assigned' in answers) {
         taskData.metadata.assigned = answers.assigned;

package/src/controller/burndown.js

@@ -5,6 +5,61 @@ const term = require('terminal-kit').terminal;
 const chrono = require('chrono-node');
 const formatDate = require('dateformat');
 
+const getLabelPlacements = (from, to, width, dateFormat, maxLabels) => {
+  for (let count = maxLabels; count >= 1; count--) {
+    const placements = [];
+    let previousEnd = -1;
+
+    for (let i = 0; i < count; i++) {
+      const ratio = count === 1 ? 0 : i / (count - 1);
+      const position = Math.round(ratio * (width - 1));
+      const value = new Date(from.getTime() + Math.round((to.getTime() - from.getTime()) * ratio));
+      const label = formatDate(value, dateFormat);
+
+      let start = position - Math.floor(label.length / 2);
+      if (start < 0) {
+        start = 0;
+      }
+      if (start + label.length > width) {
+        start = Math.max(0, width - label.length);
+      }
+
+      const end = start + label.length - 1;
+      if (i > 0 && start <= previousEnd + 1) {
+        placements.length = 0;
+        break;
+      }
+
+      placements.push({ position, start, label, end });
+      previousEnd = end;
+    }
+
+    if (placements.length) {
+      return placements;
+    }
+  }
+
+  return [];
+};
+
+const renderXAxisLabels = (from, to, width, dateFormat, leftPadding) => {
+  const sampleLabel = formatDate(from, dateFormat);
+  const maxLabels = Math.max(1, Math.floor((width + 2) / (sampleLabel.length + 2)));
+  const placements = getLabelPlacements(from, to, width, dateFormat, maxLabels);
+
+  const ticks = Array(width).fill(' ');
+  const labels = Array(width).fill(' ');
+
+  for (const placement of placements) {
+    ticks[placement.position] = '|';
+    for (let i = 0; i < placement.label.length; i++) {
+      labels[placement.start + i] = placement.label[i];
+    }
+  }
+
+  return `${leftPadding}${ticks.join('')}\n${leftPadding}${labels.join('')}`;
+};
+
 module.exports = async args => {
 
   // Make sure kanbn has been initialised
@@ -72,18 +127,23 @@ module.exports = async args => {
 
       // Render chart
       const PADDING = '     ';
-      const width = term.width - (PADDING.length + 1);
+      const width = Math.max(1, term.width - (PADDING.length + 1));
 
       const plots = [];
-      for (s of data.series) {
-        const plot = [], delta = Math.floor((s.to.getTime() - s.from.getTime()) / width);
+      for (const s of data.series) {
+        const plot = [];
+        const span = Math.max(1, s.to.getTime() - s.from.getTime());
+        const delta = width > 1 ? span / (width - 1) : 0;
         for (let i = 0; i < width; i++) {
-          plot.push((s.dataPoints.find(d => d.x >= new Date(s.from.getTime() + i * delta)) || s.dataPoints[0]).y);
+          const x = new Date(s.from.getTime() + Math.round(i * delta));
+          plot.push((s.dataPoints.find(d => d.x >= x) || s.dataPoints[0]).y);
         }
         plots.push(plot);
       }
+
+      const referenceSeries = data.series[0];
       const dateFormat = kanbn.getDateFormat(index);
-      console.log(`${formatDate(s.from, dateFormat)} to ${formatDate(s.to, dateFormat)}:`);
+      console.log(`${formatDate(referenceSeries.from, dateFormat)} to ${formatDate(referenceSeries.to, dateFormat)}:`);
       console.log(asciichart.plot(
         plots,
         {
@@ -99,6 +159,13 @@ module.exports = async args => {
           ]
         }
       ));
+      console.log(renderXAxisLabels(
+        referenceSeries.from,
+        referenceSeries.to,
+        width,
+        dateFormat,
+        ' '.repeat(PADDING.length + 1)
+      ));
     }
   })
   .catch(error => {

package/src/controller/edit.js

@@ -23,6 +23,11 @@ async function interactive(taskData, taskIds, columnName, columnNames) {
     'due' in taskData.metadata &&
     taskData.metadata.due != null
   );
+  const postponedDateExists = (
+    'metadata' in taskData &&
+    'postponed' in taskData.metadata &&
+    taskData.metadata.postponed != null
+  );
   const assignedExists = (
     'metadata' in taskData &&
     'assigned' in taskData.metadata &&
@@ -101,6 +106,46 @@ async function interactive(taskData, taskIds, columnName, columnNames) {
       format: ['Y', '/', 'MM', '/', 'DD'],
       when: answers => answers.setDue || answers.editDue === 'edit'
     },
+    {
+      type: 'expand',
+      name: 'editPostponed',
+      message: 'Edit or remove postponed date?',
+      default: 'none',
+      when: answers => postponedDateExists,
+      choices: [
+        {
+          key: 'e',
+          name: 'Edit',
+          value: 'edit'
+        },
+        {
+          key: 'r',
+          name: 'Remove',
+          value: 'remove'
+        },
+        new inquirer.Separator(),
+        {
+          key: 'n',
+          name: 'Do nothing',
+          value: 'none'
+        }
+      ]
+    },
+    {
+      type: 'confirm',
+      name: 'setPostponed',
+      message: 'Set a postponed date?',
+      default: false,
+      when: answers => !postponedDateExists
+    },
+    {
+      type: 'datepicker',
+      name: 'postponed',
+      message: 'Postponed date:',
+      default: postponedDateExists ? taskData.metadata.postponed : new Date(),
+      format: ['Y', '/', 'MM', '/', 'DD'],
+      when: answers => answers.setPostponed || answers.editPostponed === 'edit'
+    },
     {
       type: 'expand',
       name: 'editAssigned',
@@ -430,6 +475,18 @@ module.exports = async args => {
     }
   }
 
+  // Postponed date
+  if (args.postponed) {
+    if (!('metadata' in taskData)) {
+      taskData.metadata = {};
+    }
+    taskData.metadata.postponed = chrono.parseDate(utility.strArg(args.postponed));
+    if (taskData.metadata.postponed === null) {
+      utility.error('Unable to parse postponed date');
+      return;
+    }
+  }
+
   // Progress
   if (args.progress) {
     if (!('metadata' in taskData)) {
@@ -660,7 +717,17 @@ module.exports = async args => {
 
       // Due date
       if ('due' in answers) {
-        taskData.metadata.due = answers.due.toISOString();
+        taskData.metadata.due = answers.due;
+      }
+
+      // Remove postponed date
+      if ('editPostponed' in answers && answers.editPostponed === 'remove') {
+        delete taskData.metadata.postponed;
+      }
+
+      // Postponed date
+      if ('postponed' in answers) {
+        taskData.metadata.postponed = answers.postponed;
       }
 
       // Remove assigned

package/src/controller/find.js

@@ -52,6 +52,11 @@ const searchFields = [
     field: 'due',
     type: 'date'
   },
+  {
+    name: 'Postponed',
+    field: 'postponed',
+    type: 'date'
+  },
   {
     name: 'Progress',
     field: 'progress',