@basementuniverse/kanbn 2.0.0 → 2.1.0

package/routes/task.json

@@ -9,8 +9,16 @@
       "json"
     ],
     "alias": {
-      "json": ["j"]
-    }
+      "json": [
+        "j"
+      ],
+      "board": [
+        "b"
+      ]
+    },
+    "string": [
+      "board"
+    ]
   },
   "controller": "./src/controller/task",
   "help": "./docs/commands/task.txt"

package/routes/validate.json

@@ -7,13 +7,26 @@
     "boolean": [
       "json",
       "save",
-      "fix"
+      "fix",
+      "all-boards"
     ],
     "alias": {
-      "json": ["j"],
-      "save": ["s"],
-      "fix": ["f"]
-    }
+      "json": [
+        "j"
+      ],
+      "save": [
+        "s"
+      ],
+      "fix": [
+        "f"
+      ],
+      "board": [
+        "b"
+      ]
+    },
+    "string": [
+      "board"
+    ]
   },
   "controller": "./src/controller/validate",
   "help": "./docs/commands/validate.txt"

package/skills/kanbn-plan/SKILL.md

@@ -13,9 +13,18 @@ Do not use this skill to implement the project, edit source code, scaffold files
 
 Your output must stay inside the Kanbn planning surface:
 
-- `.kanbn/index.md`
+- `.kanbn/index.md` — the main board
+- `.kanbn/{board-slug}.md` — any secondary boards, in exactly the same format as the index
 - `.kanbn/tasks/*.md`
 
+A workspace may hold several boards over one shared pool of tasks. Every board file is a sibling of
+`index.md` inside `.kanbn/`, and boards own membership: a task can be referenced by several boards,
+in a different column on each. Task files never record which boards they belong to.
+
+Unless the user asks for more than one board, plan onto `.kanbn/index.md` alone. When they do want
+several, write each board file yourself in the same format, and make sure any task referenced by a
+board has a file in `.kanbn/tasks/`.
+
 Do not create application code, tests, CI files, or documentation unrelated to the Kanbn board.
 
 If the user asks for planning plus implementation, complete the planning portion in Kanbn format first and keep the planning files cleanly separated from any later work.

package/skills/kanbn-replan/SKILL.md

@@ -13,9 +13,14 @@ Do not use this skill to redesign scope, rewrite completed tasks, or invent new
 
 Your output must stay inside the Kanbn task surface:
 
-- `.kanbn/index.md`
+- `.kanbn/index.md` — the main board
+- `.kanbn/{board-slug}.md` — any secondary boards, in exactly the same format as the index
 - `.kanbn/tasks/*.md`
 
+A workspace may hold several boards over one shared pool of tasks. Rescheduling changes task
+metadata dates, which are shared, so it applies to every board at once — you do not need to touch
+board files unless a task's column changes.
+
 You may read the current board and gantt output, but the end result should be a revised schedule for existing tasks, not a new plan.
 
 Do not modify completed tasks unless the user explicitly asks to reopen them. Leave completed task descriptions, relations, and completion history intact.

package/src/board.js

@@ -178,7 +178,7 @@ module.exports = (() => {
           borderChars: 'lightRounded',
           borderAttr: { color: 'grey' },
           textAttr: { color: 'white', bgColor: 'default' },
-          width: term.width,
+          width: utility.terminalWidth(term.width),
           fit: true
         }
       );

package/src/controller/add.js

@@ -1,9 +1,13 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const inquirer = require('inquirer');
 const fuzzy = require('fuzzy');
 const chrono = require('chrono-node');
-const getGitUsername = require('git-user-name');
+const getGitUsername = require('../git-user-name');
+
+// The boards this command targets - set from --board before anything else runs
+let kanbn = workspace;
+let boardTargets = [];
 
 inquirer.registerPrompt('datepicker', require('inquirer-datepicker'));
 inquirer.registerPrompt('recursive', require('inquirer-recursive'));
@@ -235,15 +239,24 @@ async function interactiveAddUntrackedTasks(untrackedTasks, columnName, columnNa
  * @param {object} taskData
  * @param {string} columnName
  */
-function createTask(taskData, columnName) {
-  kanbn
-  .createTask(taskData, columnName)
-  .then(taskId => {
-    console.log(`Created task "${taskId}" in column "${columnName}"`);
-  })
-  .catch(error => {
+async function createTask(taskData, columnName) {
+  try {
+
+    // The task is created once, on the first target board, and then added to the others - one task
+    // file, referenced by however many boards were named
+    const [first, ...rest] = boardTargets;
+    const taskId = await first.kanbn.createTask(taskData, columnName);
+    console.log(
+      `Created task "${taskId}" in column "${columnName}"` +
+      (boardTargets.length > 1 || !first.main ? ` on board "${first.slug}"` : '')
+    );
+    for (const target of rest) {
+      await target.kanbn.addTaskToBoard(taskId, target.columnName);
+      console.log(`Added task "${taskId}" to column "${target.columnName}" on board "${target.slug}"`);
+    }
+  } catch (error) {
     utility.error(error);
-  });
+  }
 }
 
 /**
@@ -252,50 +265,44 @@ function createTask(taskData, columnName) {
  * @param {string} columnName
  */
 async function addUntrackedTasks(untrackedTasks, columnName) {
-  for (let untrackedTask of untrackedTasks) {
-    try {
-      await kanbn.addUntrackedTaskToIndex(untrackedTask, columnName);
-    } catch (error) {
-      utility.error(error);
-      return;
+  for (const target of boardTargets) {
+
+    // The column chosen interactively or on the command line applies to the first board; the others
+    // use whatever resolveBoardTargets() paired them with
+    const targetColumn = target === boardTargets[0] ? columnName : target.columnName;
+    for (let untrackedTask of untrackedTasks) {
+      try {
+        await target.kanbn.addUntrackedTaskToIndex(untrackedTask, targetColumn);
+      } catch (error) {
+        utility.error(error);
+        return;
+      }
     }
+    console.log(
+      `Added ${untrackedTasks.length} task${untrackedTasks.length !== 1 ? 's' : ''} ` +
+      `to column "${targetColumn}"` + (boardTargets.length > 1 || !target.main ? ` on board "${target.slug}"` : '')
+    );
   }
-  console.log(
-    `Added ${untrackedTasks.length} task${untrackedTasks.length !== 1 ? 's' : ''} to column "${columnName}"`
-  );
 }
 
 module.exports = async args => {
 
-  // Make sure kanbn has been initialised
-  if (!await kanbn.initialised()) {
-    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+  // Work out which boards this command targets, and which column to use on each. -b is repeatable,
+  // so one task can be created and placed on several boards at once
+  const targets = await utility.resolveBoardTargets(workspace, args);
+  if (targets === null) {
     return;
   }
-
-  // Get the index and make sure it has some columns
-  let index;
-  try {
-    index = await kanbn.getIndex();
-  } catch (error) {
-    utility.error(error);
-    return;
-  }
-  const columnNames = Object.keys(index.columns);
-  if (!columnNames.length) {
-    utility.error('No columns defined in the index\nTry running {b}kanbn init -c "column name"{b}');
-    return;
+  boardTargets = targets;
+  kanbn = targets[0].kanbn;
+  for (const target of boardTargets) {
+    target.main = await target.kanbn.isMainBoard();
   }
+  utility.showColumnFallbackNotices(boardTargets, kanbn.isVerbose(targets[0].index));
 
-  // Get column name if specified, otherwise default to the first available column
-  let columnName = columnNames[0];
-  if (args.column) {
-    columnName = utility.strArg(args.column);
-    if (columnNames.indexOf(columnName) === -1) {
-      utility.error(`Column "${columnName}" doesn't exist`);
-      return;
-    }
-  }
+  const index = targets[0].index;
+  const columnNames = Object.keys(index.columns);
+  const columnName = targets[0].columnName;
 
   // Add untracked file(s)
   if (args.untracked) {
@@ -534,8 +541,7 @@ module.exports = async args => {
           type: relation.type
         }));
       }
-      columnName = answers.column;
-      createTask(taskData, columnName);
+      createTask(taskData, answers.column);
     })
     .catch(error => {
       utility.error(error);

package/src/controller/archive.js

@@ -1,6 +1,9 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
+
 /**
  * Archive a task
  * @param {string} taskId
@@ -32,11 +35,12 @@ function listArchivedTasks() {
 
 module.exports = async args => {
 
-  // Make sure kanbn has been initialised
-  if (!await kanbn.initialised()) {
-    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+  // Work out which board this command targets
+  const scoped = await utility.resolveBoard(workspace, args);
+  if (scoped === null) {
     return;
   }
+  kanbn = scoped;
 
   // Check if we're listing archived tasks
   if (args.list) {

package/src/controller/board.js

@@ -1,12 +1,12 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const board = require('../board');
 
 module.exports = async args => {
 
-  // Make sure kanbn has been initialised
-  if (!await kanbn.initialised()) {
-    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+  // Work out which board we're showing
+  const kanbn = await utility.resolveBoard(workspace, args);
+  if (kanbn === null) {
     return;
   }
 
@@ -32,11 +32,10 @@ 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)
-    );
+  .then(async () => {
+    const verbose = !args.json && kanbn.isVerbose(index);
+    utility.showDateDriftHint(kanbn.getDateDrift(index, tasks), verbose);
+    utility.showBoardCountHint(await workspace.listBoards(), verbose);
   })
   .catch(error => {
     utility.error(error);

package/src/controller/boards.js

@@ -0,0 +1,140 @@
+const kanbn = require('../main');
+const utility = require('../utility');
+
+/**
+ * Show the list of boards in this workspace
+ * @param {object[]} boards
+ * @param {boolean} json
+ */
+function showBoards(boards, json) {
+  if (json) {
+    console.log(JSON.stringify(boards, null, 2));
+    return;
+  }
+  console.log(`${boards.length} ${boards.length === 1 ? 'board' : 'boards'}:`);
+  for (const board of boards) {
+    console.log(utility.replaceTags(`\n{b}${board.slug}{b}${board.main ? ' (main board)' : ''}`));
+    console.log(`  ${board.name}`);
+    if (board.description) {
+      console.log(`  ${board.description.split('\n')[0]}`);
+    }
+    console.log(
+      `  ${board.columns} ${board.columns === 1 ? 'column' : 'columns'}, ` +
+      `${board.tasks} ${board.tasks === 1 ? 'task' : 'tasks'}, ` +
+      `${board.completedPercentage}% complete` +
+      (board.modified ? `, last modified ${board.modified.toISOString()}` : '')
+    );
+  }
+}
+
+/**
+ * Show which boards each task appears on
+ * @param {object[]} tasks
+ * @param {boolean} all True if single-board tasks are included
+ * @param {boolean} json
+ */
+function showCrossBoardTasks(tasks, all, json) {
+  if (json) {
+    console.log(JSON.stringify(tasks, null, 2));
+    return;
+  }
+  if (!tasks.length) {
+    console.log(all ? 'No tracked tasks found' : 'No tasks appear on more than one board');
+    return;
+  }
+  console.log(
+    `${tasks.length} ${tasks.length === 1 ? 'task' : 'tasks'}` +
+    (all ? ':' : ' on more than one board:')
+  );
+  for (const task of tasks) {
+    console.log(utility.replaceTags(`\n{b}${task.id}{b}`));
+    for (const [slug, columnName] of Object.entries(task.boards)) {
+      console.log(`  ${slug}: ${columnName}`);
+    }
+  }
+}
+
+module.exports = async args => {
+
+  // Make sure kanbn has been initialised
+  if (!await kanbn.workspaceInitialised()) {
+    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+    return;
+  }
+
+  // Delete a board
+  if (args.delete) {
+    const slug = utility.strArg(args.delete);
+    let orphaned;
+    try {
+      orphaned = await kanbn.findOrphanedTasks(slug);
+    } catch (error) {
+      utility.error(error);
+      return;
+    }
+
+    // Deleting a board never deletes task files, but it can leave tasks with no board at all
+    if (orphaned.length && !args.force) {
+      utility.error(
+        `Deleting board "${slug}" would leave ${orphaned.length} ` +
+        `${orphaned.length === 1 ? 'task' : 'tasks'} untracked:\n` +
+        orphaned.map(taskId => `  ${taskId}`).join('\n') +
+        '\nUse {b}-f{b} to delete the board anyway'
+      );
+      return;
+    }
+    try {
+      await kanbn.deleteBoard(slug);
+    } catch (error) {
+      utility.error(error);
+      return;
+    }
+    console.log(
+      `Deleted board "${slug}"` +
+      (orphaned.length
+        ? `\n${orphaned.length} ${orphaned.length === 1 ? 'task is' : 'tasks are'} now untracked:\n` +
+          orphaned.map(taskId => `  ${taskId}`).join('\n')
+        : '')
+    );
+    return;
+  }
+
+  // Rename a board, i.e. kanbn boards --rename design ux --name "UX Pipeline"
+  if (args.rename) {
+    const slug = utility.strArg(args.rename);
+    const newSlug = args._[1] || slug;
+    const newName = args.name ? utility.strArg(args.name) : null;
+    if (newSlug === slug && newName === null) {
+      utility.error('No new board slug or name specified\nTry running {b}kanbn boards --rename "board-slug" "new-slug"{b}');
+      return;
+    }
+    try {
+      const renamedSlug = await kanbn.renameBoard(slug, newSlug, newName);
+      console.log(
+        renamedSlug === slug
+          ? `Renamed board "${slug}" to "${newName}"`
+          : `Renamed board "${slug}" to "${renamedSlug}"`
+      );
+    } catch (error) {
+      utility.error(error);
+    }
+    return;
+  }
+
+  // Show which boards each task appears on
+  if (args.tasks) {
+    try {
+      showCrossBoardTasks(await kanbn.getCrossBoardTasks(args.all), args.all, args.json);
+    } catch (error) {
+      utility.error(error);
+    }
+    return;
+  }
+
+  // List boards
+  try {
+    showBoards(await kanbn.getBoardsSummary(), args.json);
+  } catch (error) {
+    utility.error(error);
+  }
+};

package/src/controller/burndown.js

@@ -1,10 +1,13 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const asciichart = require('asciichart');
 const term = require('terminal-kit').terminal;
 const chrono = require('chrono-node');
 const formatDate = require('dateformat');
 
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
+
 const getLabelPlacements = (from, to, width, dateFormat, maxLabels) => {
   for (let count = maxLabels; count >= 1; count--) {
     const placements = [];
@@ -62,11 +65,12 @@ const renderXAxisLabels = (from, to, width, dateFormat, leftPadding) => {
 
 module.exports = async args => {
 
-  // Make sure kanbn has been initialised
-  if (!await kanbn.initialised()) {
-    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+  // Work out which board this command targets
+  const scoped = await utility.resolveBoard(workspace, args);
+  if (scoped === null) {
     return;
   }
+  kanbn = scoped;
   const index = await kanbn.getIndex();
 
   // Get sprint numbers or names
@@ -127,7 +131,7 @@ module.exports = async args => {
 
       // Render chart
       const PADDING = '     ';
-      const width = Math.max(1, term.width - (PADDING.length + 1));
+      const width = Math.max(1, utility.terminalWidth(term.width) - (PADDING.length + 1));
 
       const plots = [];
       for (const s of data.series) {

package/src/controller/comment.js

@@ -1,7 +1,10 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const inquirer = require('inquirer');
-const getGitUsername = require('git-user-name');
+const getGitUsername = require('../git-user-name');
+
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
 
 /**
  * Add a comment interactively
@@ -51,11 +54,12 @@ function addComment(taskId, text, author) {
 
 module.exports = async args => {
 
-  // Make sure kanbn has been initialised
-  if (!await kanbn.initialised()) {
-    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+  // Work out which board this command targets
+  const scoped = await utility.resolveBoard(workspace, args);
+  if (scoped === null) {
     return;
   }
+  kanbn = scoped;
 
   // Get the task that we're add a comment to
   const taskId = args._[1];

package/src/controller/edit.js

@@ -1,9 +1,12 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const inquirer = require('inquirer');
 const fuzzy = require('fuzzy');
 const chrono = require('chrono-node');
-const getGitUsername = require('git-user-name');
+const getGitUsername = require('../git-user-name');
+
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
 
 inquirer.registerPrompt('datepicker', require('inquirer-datepicker'));
 inquirer.registerPrompt('recursive', require('inquirer-recursive'));
@@ -455,11 +458,12 @@ function updateTask(taskId, taskData, columnName, unsetFields = []) {
 
 module.exports = async args => {
 
-  // Make sure kanbn has been initialised
-  if (!await kanbn.initialised()) {
-    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+  // Work out which board this command targets
+  const scoped = await utility.resolveBoard(workspace, args);
+  if (scoped === null) {
     return;
   }
+  kanbn = scoped;
 
   // Get the task that we're editing
   const taskId = args._[1];

package/src/controller/find.js

@@ -1,9 +1,12 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const inquirer = require('inquirer');
 const chrono = require('chrono-node');
 const yaml = require('yamljs');
 
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
+
 inquirer.registerPrompt('recursive', require('inquirer-recursive'));
 
 const searchFields = [
@@ -213,12 +216,11 @@ async function interactive() {
  * @param {boolean} quiet
  * @param {boolean} json
  */
-function findTasks(filters, quiet, json) {
+function findTasks(filters, quiet, json, allBoards = false) {
   const removeEmptyProperties = o => Object.fromEntries(Object.entries(o).filter(
     ([k, v]) => !(Array.isArray(v) && v.length == 0) && !!v
   ));
-  kanbn
-  .search(filters, quiet)
+  (allBoards ? kanbn.searchAllBoards(filters, quiet) : kanbn.search(filters, quiet))
   .then(results => {
     if (quiet) {
       console.log(json ? JSON.stringify(results, null, 2) : results.join('\n'));
@@ -309,11 +311,12 @@ function convertDateFilters(filters, filterName) {
 
 module.exports = async args => {
 
-  // Make sure kanbn has been initialised
-  if (!await kanbn.initialised()) {
-    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+  // Work out which board this command targets
+  const scoped = await utility.resolveBoard(workspace, args);
+  if (scoped === null) {
     return;
   }
+  kanbn = scoped;
 
   // Get the index and make sure it has some columns
   let index;
@@ -487,7 +490,7 @@ module.exports = async args => {
             filter.value
           );
         }
-        findTasks(filters, !otherAnswers.nonquiet, otherAnswers.json);
+        findTasks(filters, !otherAnswers.nonquiet, otherAnswers.json, !!args['all-boards']);
       })
       .catch(error => {
         utility.error(error);
@@ -499,6 +502,6 @@ module.exports = async args => {
 
   // Otherwise create task non-interactively
   } else {
-    findTasks(filters, args.quiet, args.json);
+    findTasks(filters, args.quiet, args.json, !!args['all-boards']);
   }
 };

package/src/controller/gantt.js

@@ -1,8 +1,11 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const formatDate = require('dateformat');
 const chrono = require('chrono-node');
 
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
+
 const NOW_MARKER = '┆';
 const ANSI_RESET = '\x1b[0m';
 const ANSI_FG_LINE = '\x1b[97m';
@@ -313,11 +316,12 @@ function truncateName(name, maxWidth) {
 
 module.exports = async args => {
 
-  // Make sure kanbn has been initialised
-  if (!await kanbn.initialised()) {
-    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+  // Work out which board this command targets
+  const scoped = await utility.resolveBoard(workspace, args);
+  if (scoped === null) {
     return;
   }
+  kanbn = scoped;
   const index = await kanbn.getIndex();
 
   // Get assigned

package/src/controller/history.js

@@ -1,8 +1,11 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const chrono = require('chrono-node');
 const formatDate = require('dateformat');
 
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
+
 function formatHistoryEvent(event) {
 	const details = [];
 	if ('column' in event.event) {
@@ -29,11 +32,12 @@ function formatMetadataEvent(event, dateFormat) {
 
 module.exports = async args => {
 
-	// Make sure kanbn has been initialised
-	if (!await kanbn.initialised()) {
-		utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+	// Work out which board this command targets
+	const scoped = await utility.resolveBoard(workspace, args);
+	if (scoped === null) {
 		return;
 	}
+	kanbn = scoped;
 	const index = await kanbn.getIndex();
 
 	// Get sprint numbers or names