@basementuniverse/kanbn 2.0.0 → 2.5.0

package/example/advanced/kanbn.yml

@@ -53,6 +53,71 @@ columnSorting:
 
 dateFormat: yyyy-mm-dd
 
+# The people who work on this workspace. A contributor can be a bare name or an
+# object; `name` is the value written into a task's `assigned` field and a
+# comment's `author`, and `aliases` catch the other spellings that mean the same
+# person. The list is advisory - `assigned` stays free text and is never
+# validated against it. Run `kanbn contributors --usage` to see which spellings
+# are already in use. See docs/contributors.md.
+contributors:
+  - name: Ana
+    email: ana@example.com
+    aliases:
+      - ana
+      - Ana Ruiz
+  - name: Ben
+    email: ben@example.com
+    aliases:
+      - ben
+
+# Rules that fire when a task changes. Actions only run during commands that
+# change something - never during `board`, `find` or `burndown` - and nothing a
+# rule writes can fire another rule. `--no-actions` on any of those commands, or
+# KANBN_NO_ACTIONS=1, steps around a rule that is misbehaving.
+# See docs/actions.md.
+actions:
+  # `task.started` is a transition rather than an operation: it fires when the
+  # task wasn't started before and is now, whatever caused it. It reads
+  # startedColumns above, so adding another started column doesn't break it.
+  - name: start-work
+    on: task.started
+    then:
+      - assign: '@me'
+      - addTag: active
+      - removeTag: ready
+
+  - name: close-out
+    on: task.completed
+    then:
+      - removeTag: active
+      - setProgress: 1
+      - set: { closedBy: '@me' }
+
+  # `reviewedAt` above is stamped by the column linkage; the rule runs after it,
+  # so it can see and override anything that stamping wrote.
+  - name: flag-review
+    on: task.moved
+    when:
+      toColumn: Review
+    then:
+      - addTag: needs-review
+      - comment: 'Review requested by @me'
+
+  # `for` points the verbs at related tasks instead of this one. Children carry
+  # the `child-of` relation, so `incoming` finds them from the epic.
+  - name: epic-blocks-children
+    on: task.moved
+    when:
+      tag: epic
+      toColumn: Blocked
+    for:
+      related: child-of
+      direction: incoming
+      where:
+        is-completed: false
+    then:
+      - addTag: blocked-by-epic
+
 # Custom fields (team, storyPoints, ...) can be interpolated here because they
 # are declared in customFields above. See docs/index-structure.md for the full
 # list of available variables.

package/example/boards/.kanbn/design.md

@@ -0,0 +1,31 @@
+---
+# Board-scoped: this board has its own workflow, and its own idea of started and completed
+startedColumns:
+  - Designing
+completedColumns:
+  - 'Signed Off'
+
+# ...and its own state fields, so design progress is tracked separately from engineering progress on
+# the same shared task files. Without these, moving a task to "Signed Off" here would set the
+# shared `completed` date and mark it done on the engineering board too
+startedField: designStartedAt
+completedField: designSignedOffAt
+---
+
+# Design Pipeline
+
+Design work across the product, tracked separately from engineering delivery. Tasks here are the
+same task files the engineering board uses - a task can sit in a different column on each.
+
+## Ideas
+
+- [design-onboarding-checklist](tasks/design-onboarding-checklist.md)
+
+## Designing
+
+- [build-tenant-settings-page](tasks/build-tenant-settings-page.md)
+- [refresh-marketing-site](tasks/refresh-marketing-site.md)
+
+## Signed Off
+
+- [create-organization-switcher](tasks/create-organization-switcher.md)

package/example/boards/.kanbn/index.md

@@ -0,0 +1,44 @@
+---
+# Board-scoped: these belong to the main board alone, and are NOT inherited by design.md
+startedColumns:
+  - 'In Progress'
+completedColumns:
+  - Done
+
+# Workspace-scoped: with no config file these live here, and every board inherits them. A custom
+# field has to be declared once for the whole workspace, because one task file has to parse
+# identically for every board that references it
+customFields:
+  - name: designStartedAt
+    type: date
+  - name: designSignedOffAt
+    type: date
+taskWorkloadTags:
+  Tiny: 1
+  Small: 2
+  Medium: 3
+  Large: 5
+  Huge: 8
+---
+
+# Example SaaS Project
+
+The engineering board. Design work on the same tasks is tracked separately on the `design` board -
+run `kanbn boards` to see both, and `kanbn boards --tasks` to see which tasks span them.
+
+## Backlog
+
+- [refresh-marketing-site](tasks/refresh-marketing-site.md)
+- [add-usage-alert-emails](tasks/add-usage-alert-emails.md)
+
+## Todo
+
+- [create-organization-switcher](tasks/create-organization-switcher.md)
+
+## In Progress
+
+- [build-tenant-settings-page](tasks/build-tenant-settings-page.md)
+
+## Done
+
+- [ship-billing-portal](tasks/ship-billing-portal.md)

package/example/boards/.kanbn/tasks/add-usage-alert-emails.md

@@ -0,0 +1,19 @@
+---
+created: 2026-07-09T15:00:00.000Z
+tags:
+  - Medium
+---
+
+# Add Usage Alert Emails
+
+Warn an organisation by email when it crosses 80% and 100% of its plan's usage allowance.
+
+Engineering-only work, so it never reaches the design board.
+
+## History
+
+- type: created
+  date: 2026-07-09T15:00:00.000Z
+  column: Backlog
+  fromProgress: 0
+  toProgress: 0

package/example/boards/.kanbn/tasks/build-tenant-settings-page.md

@@ -0,0 +1,43 @@
+---
+created: 2026-07-02T09:15:00.000Z
+updated: 2026-07-14T11:30:00.000Z
+started: 2026-07-10T09:00:00.000Z
+designStartedAt: 2026-07-06T10:00:00.000Z
+assigned: priya
+tags:
+  - Medium
+---
+
+# Build Tenant Settings Page
+
+A single place for an organisation's owner to manage name, logo, timezone and default roles.
+
+This task is on both boards: `In Progress` on the engineering board and `Designing` on the design
+board. Its `started` date is the engineering start; `designStartedAt` is when design picked it up.
+
+## Sub-tasks
+
+- [x] Settings form layout
+- [ ] Logo upload and cropping
+- [ ] Role defaults
+
+## History
+
+- type: created
+  date: 2026-07-02T09:15:00.000Z
+  column: Backlog
+  fromProgress: 0
+  toProgress: 0
+- type: added
+  date: 2026-07-06T10:00:00.000Z
+  column: Ideas
+  board: design
+- type: moved
+  date: 2026-07-06T10:00:00.000Z
+  fromColumn: Ideas
+  toColumn: Designing
+  board: design
+- type: moved
+  date: 2026-07-10T09:00:00.000Z
+  fromColumn: Backlog
+  toColumn: 'In Progress'

package/example/boards/.kanbn/tasks/create-organization-switcher.md

@@ -0,0 +1,44 @@
+---
+created: 2026-07-03T14:00:00.000Z
+updated: 2026-07-12T16:45:00.000Z
+designStartedAt: 2026-07-05T09:30:00.000Z
+designSignedOffAt: 2026-07-12T16:45:00.000Z
+assigned: sam
+tags:
+  - Small
+---
+
+# Create Organization Switcher
+
+A dropdown for moving between the organisations a user belongs to, without signing out.
+
+Design has finished with this one - it sits in `Signed Off` on the design board - but engineering
+hasn't started it, so it's still in `Todo` on the main board. Because the design board reads
+`designSignedOffAt` rather than the shared `completed` field, finishing it here doesn't mark it done
+for engineering.
+
+## Sub-tasks
+
+- [ ] Switcher component
+- [ ] Persist last-used organisation
+
+## History
+
+- type: created
+  date: 2026-07-03T14:00:00.000Z
+  column: Backlog
+  fromProgress: 0
+  toProgress: 0
+- type: added
+  date: 2026-07-05T09:30:00.000Z
+  column: Designing
+  board: design
+- type: moved
+  date: 2026-07-08T10:00:00.000Z
+  fromColumn: Backlog
+  toColumn: Todo
+- type: moved
+  date: 2026-07-12T16:45:00.000Z
+  fromColumn: Designing
+  toColumn: 'Signed Off'
+  board: design

package/example/boards/.kanbn/tasks/design-onboarding-checklist.md

@@ -0,0 +1,22 @@
+---
+created: 2026-07-11T13:20:00.000Z
+assigned: priya
+tags:
+  - Small
+---
+
+# Design Onboarding Checklist
+
+An in-product checklist walking a new organisation through its first week.
+
+This one is only on the design board - engineering hasn't picked it up, so it isn't on the main
+board at all. `kanbn status --untracked` would not list it: it is tracked, just not here.
+
+## History
+
+- type: created
+  date: 2026-07-11T13:20:00.000Z
+  column: Ideas
+  board: design
+  fromProgress: 0
+  toProgress: 0

package/example/boards/.kanbn/tasks/refresh-marketing-site.md

@@ -0,0 +1,28 @@
+---
+created: 2026-07-05T08:00:00.000Z
+updated: 2026-07-13T09:00:00.000Z
+designStartedAt: 2026-07-13T09:00:00.000Z
+assigned: priya
+tags:
+  - Large
+---
+
+# Refresh Marketing Site
+
+New landing page, pricing page and case studies, ahead of the autumn launch.
+
+Design has started, engineering hasn't - `Designing` on the design board, `Backlog` on the main one.
+This is the shape that makes per-board state fields worth having: the task genuinely is in flight on
+one board and untouched on the other.
+
+## History
+
+- type: created
+  date: 2026-07-05T08:00:00.000Z
+  column: Backlog
+  fromProgress: 0
+  toProgress: 0
+- type: added
+  date: 2026-07-13T09:00:00.000Z
+  column: Designing
+  board: design

package/example/boards/.kanbn/tasks/ship-billing-portal.md

@@ -0,0 +1,29 @@
+---
+created: 2026-06-24T10:00:00.000Z
+updated: 2026-07-07T17:10:00.000Z
+started: 2026-06-26T09:00:00.000Z
+completed: 2026-07-07T17:10:00.000Z
+assigned: sam
+tags:
+  - Large
+---
+
+# Ship Billing Portal
+
+Self-serve plan changes, payment method updates and invoice history.
+
+## History
+
+- type: created
+  date: 2026-06-24T10:00:00.000Z
+  column: Backlog
+  fromProgress: 0
+  toProgress: 0
+- type: moved
+  date: 2026-06-26T09:00:00.000Z
+  fromColumn: Backlog
+  toColumn: 'In Progress'
+- type: moved
+  date: 2026-07-07T17:10:00.000Z
+  fromColumn: 'In Progress'
+  toColumn: Done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basementuniverse/kanbn",
-  "version": "2.0.0",
+  "version": "2.5.0",
   "description": "A CLI Kanban application",
   "main": "index.js",
   "scripts": {
@@ -18,7 +18,7 @@
     "url": "git+https://github.com/basementuniverse/kanbn.git"
   },
   "engines": {
-    "node": ">=12.0.0"
+    "node": ">=16.13.0"
   },
   "keywords": [
     "kanbn",
@@ -38,7 +38,6 @@
     "dotenv": "^8.2.0",
     "front-matter": "^4.0.2",
     "fuzzy": "^0.1.3",
-    "git-user-name": "^2.0.0",
     "glob-promise": "^3.4.0",
     "humanize-duration": "^3.25.0",
     "inquirer": "^7.3.3",
@@ -47,11 +46,11 @@
     "inquirer-recursive": "github:basementuniverse/inquirer-recursive",
     "inquirer-select-line": "github:basementuniverse/inquirer-select-line",
     "jsonschema": "^1.4.0",
-    "marked": "^1.2.7",
-    "marked-terminal": "^4.1.1",
-    "minimist": "^1.2.5",
+    "marked": "^4.3.0",
+    "marked-terminal": "^5.2.0",
+    "minimist": "^1.2.8",
     "rimraf": "^3.0.2",
-    "terminal-kit": "^1.44.0",
+    "terminal-kit": "^3.1.4",
     "yamljs": "^0.3.0"
   },
   "devDependencies": {
@@ -66,5 +65,8 @@
     "qunit": "^2.13.0",
     "strip-ansi": "^6.0.0",
     "typescript": "^4.9.3"
+  },
+  "overrides": {
+    "tmp": "^0.2.7"
   }
 }

package/routes/add.json

@@ -6,7 +6,8 @@
   ],
   "args": {
     "boolean": [
-      "interactive"
+      "interactive",
+      "actions"
     ],
     "string": [
       "name",
@@ -18,19 +19,46 @@
       "due",
       "plannedStart",
       "plannedFinish",
-      "progress"
+      "progress",
+      "board"
     ],
     "alias": {
-      "interactive": ["i"],
-      "name": ["n"],
-      "description": ["d"],
-      "column": ["c"],
-      "sub-task": ["s"],
-      "tag": ["t"],
-      "relation": ["r"],
-      "due": ["e"],
-      "assigned": ["a"],
-      "untracked": ["u"]
+      "interactive": [
+        "i"
+      ],
+      "name": [
+        "n"
+      ],
+      "description": [
+        "d"
+      ],
+      "column": [
+        "c"
+      ],
+      "sub-task": [
+        "s"
+      ],
+      "tag": [
+        "t"
+      ],
+      "relation": [
+        "r"
+      ],
+      "due": [
+        "e"
+      ],
+      "assigned": [
+        "a"
+      ],
+      "untracked": [
+        "u"
+      ],
+      "board": [
+        "b"
+      ]
+    },
+    "default": {
+      "actions": true
     }
   },
   "controller": "./src/controller/add",

package/routes/archive.json

@@ -6,10 +6,22 @@
   ],
   "args": {
     "boolean": [
-      "list"
+      "list",
+      "actions"
     ],
     "alias": {
-      "list": ["l"]
+      "list": [
+        "l"
+      ],
+      "board": [
+        "b"
+      ]
+    },
+    "string": [
+      "board"
+    ],
+    "default": {
+      "actions": true
     }
   },
   "controller": "./src/controller/archive",

package/routes/board.json

@@ -9,11 +9,19 @@
       "json"
     ],
     "string": [
-      "view"
+      "view",
+      "board"
     ],
     "alias": {
-      "view": ["v"],
-      "json": ["j"]
+      "view": [
+        "v"
+      ],
+      "json": [
+        "j"
+      ],
+      "board": [
+        "b"
+      ]
     }
   },
   "controller": "./src/controller/board",

package/routes/boards.json

@@ -0,0 +1,30 @@
+{
+  "name": "Boards",
+  "commands": [
+    "boards"
+  ],
+  "args": {
+    "boolean": [
+      "json",
+      "tasks",
+      "all",
+      "force"
+    ],
+    "string": [
+      "rename",
+      "delete",
+      "name"
+    ],
+    "alias": {
+      "json": ["j"],
+      "tasks": ["t"],
+      "all": ["a"],
+      "force": ["f"],
+      "rename": ["r"],
+      "delete": ["d"],
+      "name": ["n"]
+    }
+  },
+  "controller": "./src/controller/boards",
+  "help": "./docs/commands/boards.txt"
+}

package/routes/burndown.json

@@ -13,15 +13,31 @@
       "sprint",
       "assigned",
       "column",
-      "normalise"
+      "normalise",
+      "board"
     ],
     "alias": {
-      "json": ["j"],
-      "date": ["d"],
-      "sprint": ["p"],
-      "assigned": ["a"],
-      "column": ["c"],
-      "normalise": ["n"]
+      "json": [
+        "j"
+      ],
+      "date": [
+        "d"
+      ],
+      "sprint": [
+        "p"
+      ],
+      "assigned": [
+        "a"
+      ],
+      "column": [
+        "c"
+      ],
+      "normalise": [
+        "n"
+      ],
+      "board": [
+        "b"
+      ]
     }
   },
   "controller": "./src/controller/burndown",

package/routes/comment.json

@@ -6,15 +6,29 @@
   ],
   "args": {
     "boolean": [
-      "interactive"
+      "interactive",
+      "actions"
     ],
     "string": [
-      "text"
+      "text",
+      "board"
     ],
     "alias": {
-      "interactive": ["i"],
-      "author": ["a"],
-      "text": ["t"]
+      "interactive": [
+        "i"
+      ],
+      "author": [
+        "a"
+      ],
+      "text": [
+        "t"
+      ],
+      "board": [
+        "b"
+      ]
+    },
+    "default": {
+      "actions": true
     }
   },
   "controller": "./src/controller/comment",

package/routes/contributors.json

@@ -0,0 +1,18 @@
+{
+  "name": "Contributors",
+  "commands": [
+    "contributors"
+  ],
+  "args": {
+    "boolean": [
+      "json",
+      "usage"
+    ],
+    "alias": {
+      "json": ["j"],
+      "usage": ["u"]
+    }
+  },
+  "controller": "./src/controller/contributors",
+  "help": "./docs/commands/contributors.txt"
+}