@basementuniverse/kanbn 2.0.0 → 2.1.0

package/README.md

@@ -4,7 +4,7 @@ A CLI kanban board application.
 
 Documentation can be found [here](./docs/index.md).
 
-Ready-to-run example boards live in [`example`](./example) - a [basic board](./example/basic), one demonstrating [views and lanes](./example/views), and one demonstrating [advanced configuration](./example/advanced).
+Ready-to-run example workspaces live in [`example`](./example) - a [basic board](./example/basic), one demonstrating [views and lanes](./example/views), one demonstrating [multiple boards](./example/boards), and one demonstrating [advanced configuration](./example/advanced).
 
 ## Installation
 
@@ -24,6 +24,7 @@ Where <command> is one of:
   version ....... Show package version
   init .......... Initialise kanbn board
   board ......... Show the kanbn board
+  boards ........ List the boards in this workspace
   task .......... Show a kanbn task
   add ........... Add a kanbn task
   edit .......... Edit a kanbn task

package/docs/advanced-configuration.md

@@ -8,6 +8,8 @@ If any project options are added to the index file, then the next time Kanbn wri
 
 _Note: in future, it might be possible to split project options between the index and configuration files, but for now configuration must be saved inside only one of these files._
 
+This applies to the **main board**. In a workspace with [several boards](multiple-boards.md), a secondary board's own options always live in that board file's front matter, and a board-local operation never writes to the configuration file.
+
 _Note: Kanbn rewrites whichever file holds the project options every time it saves them (`kanbn add`, `kanbn move`, `kanbn sort --save`, `kanbn validate --save`, and so on). The YAML is regenerated, so formatting and comments in that file are not preserved._
 
 ## Configuring default locations
@@ -48,3 +50,24 @@ This will rename the folder where tasks are stored. By default this is `tasks`.
 ### `archiveFolder`
 
 This will rename the archive folder where archived tasks are stored. By default this is `archive`. It is relative to the main folder.
+
+## Multiple boards
+
+Two more workspace-scoped options control [multiple boards](multiple-boards.md): `defaultBoard` names the board that commands target when `-b` isn't given, and `boards` controls discovery, display order and per-board options.
+
+```yaml
+defaultBoard: design
+boards:
+  exclude:
+    - notes.md
+  order:
+    - index
+    - design
+  design:
+    hiddenColumns:
+      - Ideas
+```
+
+Note that `indexFile` also sets the **main board's slug**: with `indexFile: board.md`, the main board's slug is `board`, and `main` / `default` still resolve to it.
+
+Where a configuration file exists, everything in it is inherited by every board — it is workspace-level by construction, so a board-scoped option declared there is a deliberate statement about all boards. Where there is no configuration file, the workspace options live in the main board's front matter, and only the workspace-scoped ones propagate; `startedColumns`, `views` and the rest stay with the main board.

package/docs/commands/add.txt

@@ -70,3 +70,12 @@ Examples:
 
   {b}kanbn a -ui -f "my-task-3" -f "my-task-4" -c "Done"{b}
     Interactively adds untracked tasks "my-task-3.md" and "my-task-4.md" to the "Done" column.
+
+  {b}kanbn add --board "board-slug"{b}
+  {b}kanbn add -b "board-slug"{b}
+    Add the task to a board other than the main one. This option can be repeated to put one task on
+    several boards at once - the task file is created once and every board named references it:
+      {b}kanbn add -n "Task" -b index -b design -c Todo -c Designing{b}
+    Each {b}-b{b} pairs with the {b}-c{b} in the same position; boards with no {b}-c{b} of their own
+    use the first one given, and a board that hasn't got that column falls back to its first column
+    with a notice. With a single board an unknown column is still an error.

package/docs/commands/archive.txt

@@ -10,3 +10,8 @@ Options:
   {b}kanbn archive --list{b}
   {b}kanbn archive -l{b}
     Show a list of archived task filenames.
+
+  {b}kanbn archive "task-id" --board "board-slug"{b}
+  {b}kanbn archive "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/board.txt

@@ -13,3 +13,8 @@ Options:
   {b}kanbn board -j{b}
     Output raw data instead of rendering the board. The data will be returned in JSON format.
     This is the quickest way to check what a view's filters actually match.
+
+  {b}kanbn board --board "board-slug"{b}
+  {b}kanbn board -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/boards.txt

@@ -0,0 +1,34 @@
+{b}kanbn boards{b}
+
+List the boards in this workspace.
+
+A board is a markdown file directly inside the kanbn folder, in the same format as the index. The
+index file is the main board; every other markdown file beside it is a secondary board. All boards
+share one task folder, so a task can appear on several boards, in a different column on each.
+
+Create a board with {b}kanbn init -b "board-slug"{b}, and target one with {b}-b "board-slug"{b} on
+any board-scoped command.
+
+Options:
+  {b}kanbn boards --tasks{b}
+  {b}kanbn boards -t{b}
+    Show every task that appears on more than one board, with the column it occupies on each.
+
+  {b}kanbn boards --tasks --all{b}
+  {b}kanbn boards -t -a{b}
+    Show every tracked task, not only the ones on more than one board.
+
+  {b}kanbn boards --rename "board-slug" --name "Board Name"{b}
+  {b}kanbn boards -r "board-slug" -n "Board Name"{b}
+    Rename a board. The positional argument is the new slug, and {b}--name{b} sets the display name:
+    {b}kanbn boards --rename design ux --name "UX Pipeline"{b}
+    Either the new slug or {b}--name{b} may be omitted, but not both. The main board can't be renamed.
+
+  {b}kanbn boards --delete "board-slug"{b}
+  {b}kanbn boards -d "board-slug"{b}
+    Delete a board file. Task files are never deleted, but tasks referenced only by this board become
+    untracked - if that would happen, the tasks are listed and {b}-f{b} is required to go ahead.
+
+  {b}kanbn boards --json{b}
+  {b}kanbn boards -j{b}
+    Output the board list, or the cross-board task overview, in JSON format.

package/docs/commands/burndown.txt

@@ -37,3 +37,9 @@ Options:
   {b}kanbn burndown --n "days"|"hours"|"minutes"|"seconds"{b}
     Normalise dates. Task event times (history events or legacy created/started/completed dates) will be rounded down to the nearest day, hour, minute or second. This may cause task events to be grouped together.
     If this option is set to a blank or unsupported value, the normalisation mode will be automatically selected based on the date range.
+
+  {b}kanbn burndown --board "board-slug"{b}
+  {b}kanbn burndown -b "board-slug"{b}
+    Chart a board other than the main one. Burndown measures work in flight, so a board that
+    declares no {b}startedColumns{b} has nothing to chart and says so rather than drawing an empty
+    chart.

package/docs/commands/comment.txt

@@ -15,3 +15,8 @@ Options:
   {b}kanbn comment "task-id" --text "text"{b}
   {b}kanbn comment "task-id" -t "text"{b}
     Set the comment text.
+
+  {b}kanbn comment "task-id" --board "board-slug"{b}
+  {b}kanbn comment "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/edit.txt

@@ -78,3 +78,8 @@ Options:
 
   {b}kanbn edit --remove-<custom field name>{b}
     Remove a custom metadata field.
+
+  {b}kanbn edit "task-id" --board "board-slug"{b}
+  {b}kanbn edit "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/find.txt

@@ -137,3 +137,14 @@ Examples:
 
   {b}kanbn find --count-sub-tasks 1 --count-sub-tasks 99 --progress 0 -q{b}
     List the ids of tasks that have sub-tasks but no progress yet.
+
+  {b}kanbn find --board "board-slug"{b}
+  {b}kanbn find -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+  {b}kanbn find --all-boards{b}
+    Search every board in the workspace. A task on several boards appears once, annotated with the
+    board and column it occupies on each. Without this, the search is scoped to the target board.
+    This can't be combined with {b}--sprint{b}: sprint numbers and names are relative to one board's
+    list, so there is no sensible answer across several.

package/docs/commands/gantt.txt

@@ -30,3 +30,8 @@ Options:
   {b}kanbn gantt --now "date"{b}
   {b}kanbn gantt -n "date"{b}
     Mock the current date used for the "now" line and single-date range filtering.
+
+  {b}kanbn gantt --board "board-slug"{b}
+  {b}kanbn gantt -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/help.txt

@@ -7,6 +7,7 @@ Where {b}<command>{b} is one of:
   {b}version{b} {d}.......{d} Show package version
   {b}init{b} {d}..........{d} Initialise kanbn board
   {b}board{b} {d}.........{d} Show the kanbn board
+  {b}boards{b} {d}........{d} List the boards in this workspace
   {b}task{b} {d}..........{d} Show a kanbn task
   {b}add{b} {d}...........{d} Add a kanbn task
   {b}edit{b} {d}..........{d} Edit a kanbn task

package/docs/commands/history.txt

@@ -27,3 +27,8 @@ Options:
   {b}kanbn history -t "task-id"{b}
     Filter for one or more task ids.
     This option can be repeated.
+
+  {b}kanbn history --board "board-slug"{b}
+  {b}kanbn history -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/init.txt

@@ -19,3 +19,16 @@ Options:
   {b}kanbn init --column "column"{b}
   {b}kanbn init -c "column"{b}
     Initialise a kanbn board and add the specified column. This option can be repeated to add multiple columns.
+
+  {b}kanbn init --board "board-slug"{b}
+  {b}kanbn init -b "board-slug"{b}
+    Create a secondary board beside the main one, at {b}.kanbn/board-slug.md{b}. Secondary boards
+    share the main board's task folder, so a task can appear on several boards, in a different
+    column on each. Combine with {b}-n{b}, {b}-d{b} and {b}-c{b} to set the board's name,
+    description and columns:
+      {b}kanbn init -b design -n "Design Pipeline" -c Ideas -c Designing -c "Signed Off"{b}
+    Running it again on an existing board updates its name, description and columns, exactly as
+    {b}kanbn init{b} does for the main board. A new board only picks up the default started and
+    completed columns if it actually has columns by those names, so a board with its own workflow
+    doesn't silently inherit "In Progress" and "Done".
+    The workspace has to exist first - run {b}kanbn init{b} with no {b}-b{b} to create it.

package/docs/commands/move.txt

@@ -21,3 +21,12 @@ Options:
     Move the task to a position relative to its current position in the target column.
     When specifying a negative value for N, the negative sign can be escaped with '/' or '\\' to prevent the value being recognised as an option. For example:
     {b}kanbn mv "task-1" -p \\-1 --relative{b}
+
+  {b}kanbn move "task-id" --board "board-slug"{b}
+  {b}kanbn move "task-id" -b "board-slug"{b}
+    Move the task on a board other than the main one. If the task isn't on that board yet it is
+    added, with a notice - so pulling work onto a board is one command rather than two.
+
+  {b}kanbn move "task-id" -b "board-slug" --no-add{b}
+    Refuse to move a task that isn't on the target board, instead of adding it.
+    The main board never adds implicitly: moving an untracked task there is an error either way.

package/docs/commands/remove.txt

@@ -1,12 +1,23 @@
 {b}kanbn remove "task-id"{b}
 {b}kanbn rm "task-id"{b}
 
-Remove an existing task.
+Remove an existing task. This deletes the task file and its index entry.
 
 Options:
   {b}kanbn remove "task-id" --index{b}
+  {b}kanbn remove "task-id" -x{b}
     Only remove the task from the index. The task file will not be deleted.
 
   {b}kanbn remove "task-id" --force{b}
   {b}kanbn remove "task-id" -f{b}
     Force remove the task without asking for confirmation.
+
+  {b}kanbn remove "task-id" --board "board-slug"{b}
+  {b}kanbn remove "task-id" -b "board-slug"{b}
+    Remove the task from that board. Combine this with {b}--index{b} to remove it from that board
+    only - boards own membership, so the task file and its entries on every other board are
+    untouched.
+
+  {b}kanbn remove "task-id" --all-boards{b}
+    Task files are shared between boards, so deleting one while another board still references it is
+    refused. This removes the task from every board that references it, then deletes the file.

package/docs/commands/rename.txt

@@ -11,3 +11,8 @@ Options:
   {b}kanbn rename "task-id" --name "name"{b}
   {b}kanbn rename "task-id" -n "name"{b}
     Rename the task with the specified name. This option is required if not renaming a task interactively.
+
+  {b}kanbn rename "task-id" --board "board-slug"{b}
+  {b}kanbn rename "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/restore.txt

@@ -10,3 +10,9 @@ Options:
   {b}kanbn restore "task-id" --column "column"{b}
   {b}kanbn restore "task-id" -c "column"{b}
     Restore a task from the archive and place it in the specified column.
+
+  {b}kanbn restore "task-id" --board "board-slug"{b}
+  {b}kanbn restore "task-id" -b "board-slug"{b}
+    Restore the task to that board only. Without this, the task goes back to every board it was on
+    when it was archived, in the column it occupied on each. A board that has since been deleted is
+    reported and skipped rather than failing the restore.

package/docs/commands/sort.txt

@@ -107,3 +107,8 @@ Examples:
 
   {b}kanbn sort "Todo" -z -n --count-tags{b}
     Sort tasks in the "Todo" column first by name, then by the number of tags, all in descending order
+
+  {b}kanbn sort "column" --board "board-slug"{b}
+  {b}kanbn sort "column" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/sprint.txt

@@ -15,3 +15,12 @@ Options:
   {b}kanbn sprint --description "description"{b}
   {b}kanbn sprint -d "description"{b}
     Start a new sprint with the specified description.
+
+  {b}kanbn sprint --board "board-slug"{b}
+  {b}kanbn sprint -b "board-slug"{b}
+    Add a sprint from the context of another board. Sprints are workspace-level by default, so this
+    appends to the workspace list and says so. A board that declares its own {b}sprints{b} in its
+    front matter gets the sprint appended there instead, auto-named {b}{Board name} Sprint {n}{b} so
+    that two boards' sprints can't be confused.
+    A board with its own list can't see the workspace sprints at all - that's the cost of forking,
+    and it's why forking is a deliberate front-matter edit rather than a flag.

package/docs/commands/status.txt

@@ -15,7 +15,11 @@ Options:
 
   {b}kanbn status --untracked{b}
   {b}kanbn status -u{b}
-    Show a list of untracked task filenames.
+    Show a list of untracked task filenames. "Untracked" is workspace-scoped: a task is tracked if
+    any board references it, so this lists task files that are on no board at all.
+    When other boards track tasks that the target board doesn't, they're listed separately under
+    {b}tasksOnOtherBoards{b}, with the column each one occupies - the "what could I pull onto this
+    board" list.
 
   {b}kanbn status --due{b}
   {b}kanbn status -e{b}
@@ -33,3 +37,8 @@ Options:
     This option can be repeated - if multiple dates are specified, show task workloads for tasks between the earliest and latest dates.
     The date can be in (almost) any format.
     This option will be ignored if the --quiet or --sprint options are set.
+
+  {b}kanbn status --board "board-slug"{b}
+  {b}kanbn status -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/task.txt

@@ -7,3 +7,8 @@ Options:
   {b}kanbn task "task-id" --json{b}
   {b}kanbn task "task-id" -j{b}
     Show task information in JSON format.
+
+  {b}kanbn task "task-id" --board "board-slug"{b}
+  {b}kanbn task "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/validate.txt

@@ -21,3 +21,18 @@ Options:
   {b}kanbn validate --json{b}
   {b}kanbn validate -j{b}
     Output validation errors in JSON format.
+
+  {b}kanbn validate --board "board-slug"{b}
+  {b}kanbn validate -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+  {b}kanbn validate --all-boards{b}
+    Validate every board in the workspace and the tasks each of them references, rather than just
+    the target board.
+
+In a workspace with more than one board, {b}validate{b} also reports multi-board warnings - a
+workspace-scoped option in a board file, several boards stamping the same shared date, sprints out
+of order, a task on no board at all, history naming a board that has been deleted, and markdown
+files beside the boards that don't parse as one. These are warnings, not errors: each describes a
+workspace that still works, just not the way its author probably meant it to.

package/docs/index-structure.md

@@ -130,10 +130,36 @@ customFields:
 
 Set to `false` to suppress hints and notices printed alongside normal output, such as the reminder shown when tasks have dates that don't match their column. Defaults to `true`. Hints are never shown when using `--json`.
 
+### `defaultBoard`
+
+The board that commands target when `-b` isn't given and `KANBN_BOARD` isn't set. Workspace-scoped: it belongs in the config file, or in the main board's front matter when there is no config file.
+
+See [multiple boards](multiple-boards.md).
+
+### `boards`
+
+Board discovery settings. `exclude` lists markdown files in the kanbn folder that aren't boards, `order` sets the display order for `kanbn boards`, and any other key is a board slug whose value is that board's options.
+
+```yaml
+boards:
+  exclude:
+    - notes.md
+  order:
+    - index
+    - design
+  design:
+    hiddenColumns:
+      - Ideas
+```
+
+Workspace-scoped. See [multiple boards](multiple-boards.md).
+
 ### `sprints`
 
 A list of sprints. Each sprint will have `start`, `name` and `description` properties.
 
+A board can declare its own `sprints` in its front matter, which **replaces** the workspace list for that board entirely. See [multiple boards](multiple-boards.md#per-board-sprints).
+
 Run `kanbn sprint --help` for more information.
 
 ### `defaultTaskWorkload`

package/docs/index.md

@@ -9,6 +9,7 @@ To get started quickly, check out the [Quick Start](quick-start.md) guide.
 - [Quick Start](quick-start.md)
 - [Index Structure](index-structure.md) — the board file and all project options
 - [Task Structure](task-structure.md) — task files, metadata, sub-tasks, relations, comments and history
+- [Multiple Boards](multiple-boards.md) — several boards over one shared pool of tasks
 - [Views](views.md) — custom board layouts, columns and lanes
 - [Filtering and Sorting](filtering-and-sorting.md) — the filter and sorter model shared by `find`, `sort` and views
 - [Advanced Configuration](advanced-configuration.md)
@@ -16,12 +17,13 @@ To get started quickly, check out the [Quick Start](quick-start.md) guide.
 
 ## Examples
 
-The [`example`](../example) directory contains ready-to-run boards:
+The [`example`](../example) directory contains ready-to-run workspaces:
 
 | Example | Demonstrates |
 | --- | --- |
 | [`example/basic`](../example/basic) | A typical board: columns, tags, workload, sprints |
 | [`example/views`](../example/views) | Views, lanes, filters and sorters |
+| [`example/boards`](../example/boards) | Multiple boards over one shared pool of tasks, with per-board state fields |
 | [`example/advanced`](../example/advanced) | A `kanbn.yml` config file, custom fields, column sorting and a custom task template |
 
 Run any Kanbn command from inside one of those directories to try it out.