@basementuniverse/kanbn 1.1.0 → 2.0.0

package/example/views/.kanbn/tasks/build-webhook-retry-queue.md

@@ -0,0 +1,15 @@
+---
+created: 2026-07-07T09:00:00.000Z
+updated: 2026-07-14T09:00:00.000Z
+started: 2026-07-11T09:00:00.000Z
+assigned: Ben
+progress: 0.3
+due: 2026-10-01T17:00:00.000Z
+tags:
+  - Feature
+  - Large
+---
+
+# Build Webhook Retry Queue
+
+Retry failed webhook deliveries with exponential backoff.

package/example/views/.kanbn/tasks/fix-avatar-upload-crash.md

@@ -0,0 +1,13 @@
+---
+created: 2026-07-03T09:00:00.000Z
+updated: 2026-07-03T09:00:00.000Z
+assigned: Ben
+due: 2026-07-20T17:00:00.000Z
+tags:
+  - Bug
+  - Small
+---
+
+# Fix Avatar Upload Crash
+
+Uploading a PNG larger than 5MB crashes the avatar cropper.

package/example/views/.kanbn/tasks/fix-expired-session-redirect.md

@@ -0,0 +1,15 @@
+---
+created: 2026-07-06T09:00:00.000Z
+updated: 2026-07-12T09:00:00.000Z
+started: 2026-07-10T09:00:00.000Z
+assigned: Ana
+progress: 0.5
+due: 2026-07-25T17:00:00.000Z
+tags:
+  - Bug
+  - Medium
+---
+
+# Fix Expired Session Redirect
+
+Expired sessions redirect to the dashboard instead of the login page.

package/example/views/.kanbn/tasks/investigate-offline-mode.md

@@ -0,0 +1,12 @@
+---
+created: 2026-05-01T09:00:00.000Z
+updated: 2026-05-01T09:00:00.000Z
+due: 2027-01-01T17:00:00.000Z
+tags:
+  - Feature
+  - Huge
+---
+
+# Investigate Offline Mode
+
+Parked until after the search rewrite.

package/example/views/.kanbn/tasks/rewrite-search-indexer.md

@@ -0,0 +1,12 @@
+---
+created: 2026-07-04T09:00:00.000Z
+updated: 2026-07-04T09:00:00.000Z
+due: 2026-11-30T17:00:00.000Z
+tags:
+  - Feature
+  - Huge
+---
+
+# Rewrite Search Indexer
+
+Replace the nightly re-index with an incremental indexer.

package/example/views/.kanbn/tasks/tidy-up-settings-copy.md

@@ -0,0 +1,12 @@
+---
+created: 2026-07-05T09:00:00.000Z
+updated: 2026-07-05T09:00:00.000Z
+due: 2026-10-15T17:00:00.000Z
+tags:
+  - Chore
+  - Tiny
+---
+
+# Tidy Up Settings Copy
+
+Fix inconsistent capitalisation across the settings pages.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@basementuniverse/kanbn",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "A CLI Kanban application",
   "main": "index.js",
   "scripts": {
-    "test": "KANBN_ENV=test qunit ./test/**/*.test.js"
+    "test": "KANBN_ENV=test qunit ./test/**/*.test.js",
+    "coverage": "KANBN_ENV=test c8 --reporter=text --reporter=html --include=src/** --include=index.js qunit ./test/**/*.test.js"
   },
   "preferGlobal": true,
   "bin": {
@@ -55,10 +56,10 @@
   },
   "devDependencies": {
     "@types/typescript": "^2.0.0",
+    "c8": "^12.0.0",
     "capture-console": "^1.0.1",
     "faker": "^5.1.0",
     "mock-argv": "^1.1.10",
-    "mock-fs": "^4.13.0",
     "mock-require": "^3.0.3",
     "mock-stdin": "^1.0.0",
     "mockdate": "^3.0.2",

package/routes/edit.json

@@ -21,7 +21,8 @@
       "due",
       "plannedStart",
       "plannedFinish",
-      "progress"
+      "progress",
+      "unset"
     ],
     "alias": {
       "interactive": ["i"],

package/routes/validate.json

@@ -6,11 +6,13 @@
   "args": {
     "boolean": [
       "json",
-      "save"
+      "save",
+      "fix"
     ],
     "alias": {
       "json": ["j"],
-      "save": ["s"]
+      "save": ["s"],
+      "fix": ["f"]
     }
   },
   "controller": "./src/controller/validate",

package/skills/kanbn-plan/references/index-structure.md

@@ -38,6 +38,7 @@ Short project summary and planning assumptions.
 - After the description, each level-2 heading defines a column.
 - Each column should contain a markdown list of task links.
 - Each task link should point to `tasks/<task-id>.md`.
+- A task placed in a column listed in `startedColumns` or `completedColumns` should carry the matching `started` / `completed` date in its metadata. Kanbn reads task state from those dates, not from the column.
 - The link text should be the task id, not the human-readable title.
 
 ## Recommended Defaults

package/skills/kanbn-plan/references/task-structure.md

@@ -106,6 +106,8 @@ Usually omit:
 
 Add metadata only when the user supplied it or when the board already relies on it.
 
+The one exception is a task you place in a started or completed column. Kanbn decides whether a task has started or been completed from its `started` and `completed` dates, not from the column it is in, so a task placed in `In Progress` or `Done` without those dates will be reported as drifted and will be missing from burndown charts. If you place a task in one of those columns because the user told you the work is already underway or finished, write the matching date. If you don't know when it happened, leave the task in a column that doesn't imply state.
+
 Good uses of metadata:
 
 - `tags` for epics, teams, domains, or sizing labels

package/src/board.js

@@ -35,6 +35,7 @@ module.exports = (() => {
       started: 'started' in task.metadata ? formatDate(task.metadata.started, dateFormat) : '',
       completed: 'completed' in task.metadata ? formatDate(task.metadata.completed, dateFormat) : '',
       due: 'due' in task.metadata ? formatDate(task.metadata.due, dateFormat) : '',
+      assigned: 'assigned' in task.metadata ? task.metadata.assigned : '',
       tags: 'tags' in task.metadata ? task.metadata.tags : [],
       subTasks: task.subTasks,
       relations: task.relations,

package/src/controller/board.js

@@ -32,6 +32,12 @@ module.exports = async args => {
   // Show the board
   board
   .show(index, tasks, args.view, args.json)
+  .then(() => {
+    utility.showDateDriftHint(
+      kanbn.getDateDrift(index, tasks),
+      !args.json && kanbn.isVerbose(index)
+    );
+  })
   .catch(error => {
     utility.error(error);
   });

package/src/controller/edit.js

@@ -412,7 +412,7 @@ async function interactive(taskData, taskIds, columnName, columnNames) {
           type: 'input',
           name: 'type',
           message: 'Relation type:',
-          default: answers => taskData.relations.find(relation => relation.task === answers.selectRelation).task,
+          default: answers => taskData.relations.find(relation => relation.task === answers.selectRelation).type,
           when: answers => answers.editRelation === 'edit'
         }
       ]
@@ -420,15 +420,31 @@ async function interactive(taskData, taskIds, columnName, columnNames) {
   ]);
 }
 
+/**
+ * Metadata fields that can be cleared with --unset, in addition to any custom fields defined in
+ * the index options
+ */
+const UNSETTABLE_FIELDS = [
+  'started',
+  'completed',
+  'due',
+  'plannedStart',
+  'plannedFinish',
+  'assigned',
+  'progress',
+  'tags'
+];
+
 /**
  * Update a task
  * @param {string} taskId
  * @param {object} taskData
  * @param {?string} columnName
+ * @param {string[]} [unsetFields=[]]
  */
-function updateTask(taskId, taskData, columnName) {
+function updateTask(taskId, taskData, columnName, unsetFields = []) {
   kanbn
-  .updateTask(taskId, taskData, columnName)
+  .updateTask(taskId, taskData, columnName, unsetFields)
   .then(taskId => {
     console.log(`Updated task "${taskId}"`);
   })
@@ -578,8 +594,8 @@ module.exports = async args => {
 
     // Check that the sub-tasks being removed currently exist
     for (let removedSubTask of removedSubTasks) {
-      if (taskData.subTasks.find(subTask => subTask.text === removedSubTask.text) === undefined) {
-        utility.error(`Sub-task "${removedSubTask.text}" doesn't exist`);
+      if (taskData.subTasks.find(subTask => subTask.text === removedSubTask) === undefined) {
+        utility.error(`Sub-task "${removedSubTask}" doesn't exist`);
         return;
       }
     }
@@ -633,7 +649,7 @@ module.exports = async args => {
     // Check that the tags being removed currently exist
     for (let removedTag of removedTags) {
       if (taskData.metadata.tags.indexOf(removedTag) === -1) {
-        utility.error(`Tag "${removedSubTask.text}" doesn't exist`);
+        utility.error(`Tag "${removedTag}" doesn't exist`);
         return;
       }
     }
@@ -652,8 +668,8 @@ module.exports = async args => {
 
     // Check that the relations being removed currently exist
     for (let removedRelation of removedRelations) {
-      if (taskData.relations.find(relation => relation.task === removedRelation.task) === undefined) {
-        utility.error(`Relation "${removedRelation.task}" doesn't exist`);
+      if (taskData.relations.find(relation => relation.task === removedRelation) === undefined) {
+        utility.error(`Relation "${removedRelation}" doesn't exist`);
         return;
       }
     }
@@ -754,6 +770,43 @@ module.exports = async args => {
     }
   }
 
+  // Unset metadata fields
+  const unsetFields = [];
+  if (args.unset) {
+    const customFieldNames = 'customFields' in index.options
+      ? index.options.customFields.map(customField => customField.name)
+      : [];
+    const unsettableFields = [...UNSETTABLE_FIELDS, ...customFieldNames];
+
+    // Arguments that set the value of a metadata field, so that setting and unsetting the same
+    // field in one command can be rejected instead of silently resolving one way or the other
+    const settingArgs = {
+      due: args.due,
+      plannedStart: args.plannedStart,
+      plannedFinish: args.plannedFinish,
+      progress: args.progress,
+      assigned: args.assigned,
+      tags: args.tag,
+      ...Object.fromEntries(customFieldNames.map(name => [name, args[name]]))
+    };
+
+    for (let field of utility.arrayArg(args.unset)) {
+      if (unsettableFields.indexOf(field) === -1) {
+        utility.error(
+          `Cannot unset "${field}"\nAvailable fields: ${unsettableFields.join(', ')}`
+        );
+        return;
+      }
+      if (settingArgs[field] !== undefined) {
+        utility.error(`Cannot set and unset "${field}" in the same command`);
+        return;
+      }
+      if (unsetFields.indexOf(field) === -1) {
+        unsetFields.push(field);
+      }
+    }
+  }
+
   // Update task interactively
   if (args.interactive) {
     interactive(taskData, taskIds, columnName, columnNames)
@@ -810,7 +863,7 @@ module.exports = async args => {
       // Edit or remove sub-tasks
       if ('editSubTasks' in answers) {
         for (editSubTask of answers.editSubTasks) {
-          const i = taskData.subTasks.findIndex(subTask => subTask.task === editSubTask.selectSubTask);
+          const i = taskData.subTasks.findIndex(subTask => subTask.text === editSubTask.selectSubTask);
           if (i !== -1) {
             switch (editSubTask.editSubTask) {
               case 'remove':
@@ -837,7 +890,7 @@ module.exports = async args => {
       // Remove tags
       if ('removeTags' in answers && 'metadata' in taskData && 'tags' in taskData.metadata) {
         for (removeTag of answers.removeTags) {
-          const i = taskData.metadata.tags.indexOf(removeTag.name);
+          const i = taskData.metadata.tags.indexOf(removeTag.selectTag);
           if (i !== -1) {
             taskData.metadata.tags.splice(i, 1);
           }
@@ -878,7 +931,7 @@ module.exports = async args => {
 
       // Update task
       columnName = answers.column !== currentColumnName ? answers.column : null;
-      updateTask(taskId, taskData, columnName);
+      updateTask(taskId, taskData, columnName, unsetFields);
     })
     .catch(error => {
       utility.error(error);
@@ -887,6 +940,6 @@ module.exports = async args => {
   // Otherwise edit task non-interactively
   } else {
     columnName = columnName !== currentColumnName ? columnName : null;
-    updateTask(taskId, taskData, columnName);
+    updateTask(taskId, taskData, columnName, unsetFields);
   }
 };

package/src/controller/gantt.js

@@ -64,7 +64,8 @@ function createChartCell() {
   return {
     bg: null,
     lineMask: 0,
-    arrowChar: null
+    arrowChar: null,
+    markerChar: null
   };
 }
 
@@ -121,6 +122,38 @@ function routeDependency(grid, sourceRow, sourceCol, targetRow, targetCol) {
   grid[targetRow][targetCol].arrowChar = targetCol >= routeCol ? '→' : '←';
 }
 
+function setMarker(cell, markerChar) {
+  if (!cell.arrowChar && !cell.markerChar) {
+    cell.markerChar = markerChar;
+  }
+}
+
+function routeIncomingExternalDependency(grid, row, targetCol) {
+  const arrowCol = Math.max(0, targetCol);
+  grid[row][arrowCol].arrowChar = '→';
+
+  if (arrowCol > 0) {
+    addMask(grid[row][arrowCol], DIR_LEFT);
+    addMask(grid[row][arrowCol - 1], DIR_RIGHT);
+  }
+  if (arrowCol > 1) {
+    setMarker(grid[row][arrowCol - 2], '…');
+  }
+}
+
+function routeOutgoingExternalDependency(grid, row, sourceCol, width) {
+  const arrowCol = Math.min(width - 1, sourceCol);
+  grid[row][arrowCol].arrowChar = '→';
+
+  if (arrowCol < width - 1) {
+    addMask(grid[row][arrowCol], DIR_RIGHT);
+    addMask(grid[row][arrowCol + 1], DIR_LEFT);
+  }
+  if (arrowCol < width - 2) {
+    setMarker(grid[row][arrowCol + 2], '…');
+  }
+}
+
 function buildDependencyOverlay(tasks, barGeometries, width) {
   const grid = createChartGrid(tasks.length, width);
   const taskRowMap = new Map(tasks.map((task, index) => [task.id, index]));
@@ -140,6 +173,14 @@ function buildDependencyOverlay(tasks, barGeometries, width) {
         barGeometries[targetRow].start
       );
     });
+
+    if (Array.isArray(task.externalIncomingDependencies) && task.externalIncomingDependencies.length > 0) {
+      routeIncomingExternalDependency(grid, targetRow, barGeometries[targetRow].start);
+    }
+
+    if (Array.isArray(task.externalOutgoingDependents) && task.externalOutgoingDependents.length > 0) {
+      routeOutgoingExternalDependency(grid, targetRow, barGeometries[targetRow].end, width);
+    }
   });
 
   return grid;
@@ -165,6 +206,10 @@ function renderChartRow(gridRow, barGeometry, barBackground, nowPosition) {
       return styleCell(lineChar, ANSI_FG_LINE, bg);
     }
 
+    if (cell.markerChar) {
+      return styleCell(cell.markerChar, ANSI_FG_LINE, bg);
+    }
+
     if (nowPosition === column) {
       return styleCell(NOW_MARKER, ANSI_FG_NOW, bg);
     }

package/src/controller/status.js

@@ -57,6 +57,18 @@ module.exports = async args => {
       console.log(args.json ? JSON.stringify(output, null, 2) : yaml.stringify(output, 4, 2));
     }
   })
+  .then(async () => {
+
+    // Only load tasks for the hint when it would actually be shown
+    if (args.json || args.quiet) {
+      return;
+    }
+    const index = await kanbn.getIndex();
+    if (!kanbn.isVerbose(index)) {
+      return;
+    }
+    utility.showDateDriftHint(await kanbn.findDateDrift());
+  })
   .catch(error => {
     utility.error(error);
   });

package/src/controller/task.js

@@ -13,7 +13,7 @@ function showTask(taskId, json = false) {
     .getTask(taskId)
     .then((task) => {
       if (json) {
-        console.log(task);
+        console.log(JSON.stringify(task, null, 2));
       } else {
         marked.setOptions({
           renderer: new markedTerminalRenderer(),

package/src/controller/validate.js

@@ -2,6 +2,31 @@ const kanbn = require('../main');
 const utility = require('../utility');
 const yaml = require('yamljs');
 
+/**
+ * Show a list of tasks whose dates disagree with the column they're in
+ * @param {object[]} drift
+ * @param {boolean} json
+ */
+function showDrift(drift, json) {
+  if (json) {
+    console.log(JSON.stringify(drift, null, 2));
+    return;
+  }
+  const fixable = drift.filter(d => d.fixable);
+  console.log(
+    `${drift.length} ${drift.length === 1 ? 'task has' : 'tasks have'} dates that don't match ` +
+    `${drift.length === 1 ? 'its' : 'their'} column:`
+  );
+  for (const item of drift) {
+    console.log(`  ${item.task}: ${item.message}`);
+  }
+  if (fixable.length) {
+    console.log(utility.replaceTags(
+      `\nRun {b}kanbn validate --fix{b} to fill in ${fixable.length === 1 ? 'the missing date' : 'the missing dates'}.`
+    ));
+  }
+}
+
 module.exports = async args => {
 
   // Make sure kanbn has been initialised
@@ -11,21 +36,59 @@ module.exports = async args => {
   }
 
   // Validate kanbn files
-  kanbn.validate(args.save)
-  .then(result => {
-    if (result === true) {
-      console.log('Everything OK');
-    } else {
-      utility.error(
-        `${result.length} errors found in task files:\n${(
-          args.json
-            ? JSON.stringify(result, null, 2)
-            : yaml.stringify(result, 4, 2)
-        )}`
-      );
+  let result;
+  try {
+    result = await kanbn.validate(args.save);
+  } catch (error) {
+    utility.error(error);
+    return;
+  }
+  if (result !== true) {
+    utility.error(
+      `${result.length} errors found in task files:\n${(
+        args.json
+          ? JSON.stringify(result, null, 2)
+          : yaml.stringify(result, 4, 2)
+      )}`
+    );
+    return;
+  }
+
+  // Backfill missing started and completed dates
+  if (args.fix) {
+    let fixed;
+    try {
+      fixed = await kanbn.fixDateDrift();
+    } catch (error) {
+      utility.error(error);
+      return;
     }
-  })
-  .catch(error => {
+    if (!fixed.length) {
+      console.log('Everything OK, nothing to fix');
+      return;
+    }
+    if (args.json) {
+      console.log(JSON.stringify(fixed, null, 2));
+      return;
+    }
+    console.log(`Filled in ${fixed.length} missing ${fixed.length === 1 ? 'date' : 'dates'}:`);
+    for (const item of fixed) {
+      console.log(`  ${item.task}: ${item.field} set to ${item.date.toISOString()} (from ${item.source})`);
+    }
+    return;
+  }
+
+  // Report tasks whose dates disagree with their column
+  let drift;
+  try {
+    drift = await kanbn.findDateDrift();
+  } catch (error) {
     utility.error(error);
-  });
+    return;
+  }
+  if (drift.length) {
+    showDrift(drift, args.json);
+    return;
+  }
+  console.log('Everything OK');
 };