@basementuniverse/kanbn 1.1.0 → 2.0.0

package/docs/views.md

@@ -0,0 +1,229 @@
+# Views
+
+A view is a saved board layout. Views let you re-arrange, filter and group the same set of tasks without changing the index columns or moving any tasks around.
+
+Views are defined in the `views` project option (index front matter, or `kanbn.json` / `kanbn.yml` — see [Advanced Configuration](advanced-configuration.md)) and are selected with:
+
+```bash
+kanbn board --view "view name"
+kanbn board -v "view name"
+```
+
+If the named view doesn't exist, `kanbn board` reports an error. Running `kanbn board` with no `--view` option always uses the [default board](#the-default-board), even if a view called `default` exists.
+
+A working example lives in [`example/views`](../example/views).
+
+## Structure
+
+```yaml
+views:
+  - name: 'View name'          # required
+    filters: {}                # optional, applied to every task before columns and lanes
+    columns:                   # optional, at least 1 entry if present
+      - name: 'Column name'    # required, this is the board heading
+        filters: {}            # optional
+        sorters: []            # optional
+    lanes:                     # optional
+      - name: 'Lane name'      # required
+        filters: {}            # optional
+```
+
+| Property | Where | Required | Description |
+| --- | --- | --- | --- |
+| `name` | view | yes | The name passed to `kanbn board --view`. If two views share a name, the first one wins |
+| `filters` | view | no | A [filter set](filtering-and-sorting.md#filters) applied to all tasks before anything else |
+| `columns` | view | no | The board columns, left to right. Defaults to the index columns |
+| `columns[].name` | column | yes | The column heading. It does **not** have to be an index column name |
+| `columns[].filters` | column | no | A [filter set](filtering-and-sorting.md#filters) deciding which tasks appear in this column |
+| `columns[].sorters` | column | no | A [sorter list](filtering-and-sorting.md#sorters) for tasks in this column |
+| `lanes` | view | no | Horizontal swimlanes, top to bottom. Defaults to a single lane called "All tasks" |
+| `lanes[].name` | lane | yes | The lane label |
+| `lanes[].filters` | lane | no | A [filter set](filtering-and-sorting.md#filters) applied to every column in this lane |
+
+Anything else is ignored. In particular there is **no** `hidden` property on view columns — to leave a column out of a view, just don't list it.
+
+## How a view is built
+
+For every lane, and for every column in that lane, Kanbn takes the full list of tracked tasks and:
+
+1. applies the view's root `filters` (if any);
+2. merges the column's `filters` with the lane's `filters` and applies the result;
+3. sorts what's left using the column's `sorters`.
+
+The merge in step 2 is a shallow object merge with the **lane winning**: if a column and a lane both filter on the same field, the lane's value is used. Filters on different fields combine with AND.
+
+Two consequences worth knowing:
+
+- **A column with no `filters` shows every task**, in every lane, regardless of which index column the tasks are actually in. Column names in a view are just labels. If you want a view column to show one index column, filter on it explicitly:
+
+  ```yaml
+  - name: 'In Progress'
+    filters:
+      column: 'In Progress'
+  ```
+
+- **Views can overlap.** The same task can appear in more than one column or lane if it matches more than one filter set. That's often what you want (a "Bugs" and an "Overdue" column side by side), but it does mean a view is not necessarily a partition of the board.
+
+## The default board
+
+When a view doesn't define `columns`, Kanbn builds them from the index: one column per index column, in index order, each filtered to `column: <that column name>`, and [`hiddenColumns`](index-structure.md#hiddencolumns) removed.
+
+`hiddenColumns` is only consulted when building this default column list. **A view that defines its own `columns` ignores `hiddenColumns` entirely**, so a view is also the way to see hidden columns:
+
+```yaml
+views:
+  - name: 'everything'
+    columns:
+      - name: 'All tasks (including hidden columns)'
+        sorters:
+          - field: column
+            order: ascending
+```
+
+When a view doesn't define `lanes` (or defines an empty list), a single lane called "All tasks" is used.
+
+## Lanes
+
+A lane is a horizontal band across the whole board. Every column is rendered once per lane, filtered by that lane's filters. Lanes are for grouping the same columns by some secondary dimension: assignee, tag, workload, priority, and so on.
+
+```yaml
+views:
+  - name: 'by-assignee'
+    columns:
+      - name: 'Backlog'
+        filters:
+          column: 'Backlog'
+      - name: 'In Progress'
+        filters:
+          column: 'In Progress'
+      - name: 'Done'
+        filters:
+          column: 'Done'
+    lanes:
+      - name: 'Ana'
+        filters:
+          assigned: '^Ana$'
+      - name: 'Ben'
+        filters:
+          assigned: '^Ben$'
+      - name: 'Unassigned'
+        filters:
+          assigned: '^$'
+```
+
+```
+╭──────────────────────┬──────────────────────┬──────────────────────╮
+│Backlog               │» In Progress         │✓ Done                │
+├──────────────────────┼──────────────────────┼──────────────────────┤
+│Ana                   │                      │                      │
+├──────────────────────┼──────────────────────┼──────────────────────┤
+│Add Audit Log Export  │Fix Expired Session   │Add Dark Mode Toggle  │
+│                      │Redirect              │                      │
+├──────────────────────┼──────────────────────┼──────────────────────┤
+│Ben                   │                      │                      │
+├──────────────────────┼──────────────────────┼──────────────────────┤
+│Fix Avatar Upload     │Build Webhook Retry   │                      │
+│Crash                 │Queue                 │                      │
+├──────────────────────┼──────────────────────┼──────────────────────┤
+│Unassigned            │                      │                      │
+├──────────────────────┼──────────────────────┼──────────────────────┤
+│Rewrite Search        │                      │                      │
+│Indexer               │                      │                      │
+│                      │                      │                      │
+│Tidy Up Settings Copy │                      │                      │
+╰──────────────────────┴──────────────────────┴──────────────────────╯
+```
+
+Because `assigned` is a [string filter](filtering-and-sorting.md#string-filters) matched as a regex, `'^Ana$'` matches only tasks assigned to exactly "Ana" (a bare `Ana` would also match "Ana-Maria"), and `'^$'` matches unassigned tasks, whose `assigned` value is treated as an empty string.
+
+*Note: a task that matches no lane filter simply isn't shown. Lanes don't have a catch-all.*
+
+## Examples
+
+All of these are in [`example/views/.kanbn/index.md`](../example/views/.kanbn/index.md) and can be run from the `example/views` directory.
+
+### Group by workload
+
+Columns as workload buckets, lanes splitting started from not-started work. Neither the columns nor the lanes correspond to index columns:
+
+```yaml
+- name: 'workload'
+  columns:
+    - name: 'Small (1-2)'
+      filters:
+        workload: [1, 2]
+    - name: 'Medium (3-5)'
+      filters:
+        workload: [3, 5]
+    - name: 'Large (6+)'
+      filters:
+        workload: [6, 99]
+  lanes:
+    - name: 'Not started'
+      filters:
+        column: 'Backlog'
+    - name: 'Started'
+      filters:
+        column: 'In Progress'
+```
+
+### Root filter plus per-column sorting
+
+The root `filters` narrows the whole view to bugs; the first column narrows further by due date and sorts by workload; the second column has no filters, so within this view it shows all bugs:
+
+```yaml
+- name: 'triage'
+  filters:
+    tag: Bug
+  columns:
+    - name: 'Due before Aug 2026'
+      filters:
+        due:
+          - 2020-01-01
+          - 2026-08-01
+      sorters:
+        - field: workload
+          order: descending
+    - name: 'All bugs'
+      sorters:
+        - field: name
+          order: ascending
+```
+
+## Inspecting a view
+
+`kanbn board --json` (with or without `--view`) prints the resolved board rather than rendering it, which is the quickest way to check that a view's filters do what you expect:
+
+```bash
+kanbn board -v triage --json
+```
+
+```json
+{
+  "headings": [
+    { "name": "Due before Aug 2026", "heading": "^:^+Due before Aug 2026^:" },
+    { "name": "All bugs", "heading": "^:^+All bugs^:" }
+  ],
+  "lanes": [
+    {
+      "name": "All tasks",
+      "columns": [
+        [
+          { "id": "fix-expired-session-redirect", "workload": 3, "...": "..." },
+          { "id": "fix-avatar-upload-crash", "workload": 2, "...": "..." }
+        ],
+        [
+          { "id": "fix-avatar-upload-crash", "...": "..." },
+          { "id": "fix-expired-session-redirect", "...": "..." }
+        ]
+      ]
+    }
+  ]
+}
+```
+
+## Limitations
+
+- View column `sorters` accept the same fields as `kanbn sort` and `columnSorting`, plus `column`. See [sortable fields](filtering-and-sorting.md#sortable-fields).
+- Views only affect `kanbn board`. `kanbn find`, `kanbn status`, `kanbn burndown`, `kanbn gantt` and `kanbn history` don't take a `--view` option.
+- Views are read-only: `kanbn move` and `kanbn add` still work in terms of index columns, not view columns.

package/example/README.md

@@ -0,0 +1,70 @@
+# Kanbn Examples
+
+Each subdirectory is a self-contained Kanbn workspace. `cd` into one and run any Kanbn command
+against it — nothing here affects the boards in the other directories.
+
+```bash
+cd example/views
+kanbn board -v by-assignee
+```
+
+The index and config files in these examples are commented so they can be read as documentation.
+Kanbn rewrites those files whenever it saves (`kanbn add`, `kanbn move`, `kanbn sort --save`,
+`kanbn validate --save`, ...), which reformats the YAML and strips the comments — so run mutating
+commands on a copy if you want to keep them.
+
+## [`basic`](basic)
+
+A typical in-flight product board. Demonstrates the core setup you get from `kanbn init`:
+
+- columns, with `startedColumns` and `completedColumns`
+- tags and `taskWorkloadTags` for workload calculation
+- `sprints`
+- tasks with sub-tasks, `assigned`, `progress`, `due` and `## History` sections
+
+```bash
+kanbn board
+kanbn status --due
+kanbn burndown -p "Workflow Sprint"
+kanbn gantt
+```
+
+## [`views`](views)
+
+Custom board layouts. See [Views](../docs/views.md).
+
+- `default` — the index columns, spelled out explicitly
+- `by-assignee` — the same columns, split into one lane per assignee plus an "Unassigned" lane
+- `triage` — a root filter narrowing the whole view to bugs, plus per-column filters and sorters
+- `workload` — columns as workload buckets and lanes as started/not-started
+- `everything` — a single column showing every task, including the hidden `Icebox` column
+
+```bash
+kanbn board
+kanbn board -v by-assignee
+kanbn board -v triage
+kanbn board -v workload
+kanbn board -v everything
+kanbn board -v triage --json
+```
+
+## [`advanced`](advanced)
+
+Project configuration beyond the defaults. See
+[Advanced Configuration](../docs/advanced-configuration.md).
+
+- all project options live in [`kanbn.yml`](advanced/kanbn.yml) instead of the index front matter
+- `customFields` (`team`, `storyPoints`, `needsDesign`, `reviewedAt`) that can be set, searched and sorted
+- `reviewedAtColumns`, which stamps `reviewedAt` the first time a task enters the `Review` column
+- `columnSorting`, which keeps `Backlog` sorted by workload in the index file itself
+- a custom `taskTemplate` and `dateFormat`
+- a hidden `Blocked` column
+
+```bash
+kanbn board
+kanbn find --team Platform
+kanbn find --storyPoints 3 --storyPoints 8
+kanbn find --needsDesign
+kanbn find --no-needsDesign
+kanbn sort "Backlog" --workload -z --name -a --save
+```

package/example/advanced/.kanbn/index.md

@@ -0,0 +1,26 @@
+# Advanced Example
+
+Project options for this board live in `kanbn.yml` in the workspace root rather
+than in this file's front matter. See `docs/advanced-configuration.md`.
+
+## Backlog
+
+- [add-sso-support](tasks/add-sso-support.md)
+- [refresh-marketing-site](tasks/refresh-marketing-site.md)
+- [rotate-api-keys](tasks/rotate-api-keys.md)
+
+## In Progress
+
+- [split-billing-service](tasks/split-billing-service.md)
+
+## Review
+
+- [add-rate-limiting](tasks/add-rate-limiting.md)
+
+## Done
+
+- [upgrade-node-runtime](tasks/upgrade-node-runtime.md)
+
+## Blocked
+
+- [migrate-to-new-cdn](tasks/migrate-to-new-cdn.md)

package/example/advanced/.kanbn/tasks/add-rate-limiting.md

@@ -0,0 +1,18 @@
+---
+created: 2026-06-25T09:00:00.000Z
+updated: 2026-07-18T09:00:00.000Z
+started: 2026-07-08T09:00:00.000Z
+reviewedAt: 2026-07-18T09:00:00.000Z
+assigned: Ana
+progress: 0.9
+due: 2026-07-20T17:00:00.000Z
+team: Platform
+storyPoints: 3
+needsDesign: false
+tags:
+  - Medium
+---
+
+# Add Rate Limiting
+
+Per-tenant rate limits on the public API.

package/example/advanced/.kanbn/tasks/add-sso-support.md

@@ -0,0 +1,15 @@
+---
+created: 2026-07-01T09:00:00.000Z
+updated: 2026-07-01T09:00:00.000Z
+assigned: Ana
+due: 2026-11-01T17:00:00.000Z
+team: Identity
+storyPoints: 13
+needsDesign: true
+tags:
+  - Huge
+---
+
+# Add SSO Support
+
+Support SAML and OIDC single sign-on for enterprise customers.

package/example/advanced/.kanbn/tasks/migrate-to-new-cdn.md

@@ -0,0 +1,14 @@
+---
+created: 2026-06-10T09:00:00.000Z
+updated: 2026-07-01T09:00:00.000Z
+due: 2026-12-01T17:00:00.000Z
+team: Platform
+storyPoints: 5
+needsDesign: false
+tags:
+  - Large
+---
+
+# Migrate To New CDN
+
+Blocked until the contract with the new CDN provider is signed.

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

@@ -0,0 +1,14 @@
+---
+created: 2026-07-02T09:00:00.000Z
+updated: 2026-07-02T09:00:00.000Z
+due: 2026-09-15T17:00:00.000Z
+team: Growth
+storyPoints: 5
+needsDesign: true
+tags:
+  - Medium
+---
+
+# Refresh Marketing Site
+
+Rebuild the landing pages on the new design system.

package/example/advanced/.kanbn/tasks/rotate-api-keys.md

@@ -0,0 +1,15 @@
+---
+created: 2026-07-03T09:00:00.000Z
+updated: 2026-07-03T09:00:00.000Z
+assigned: Ben
+due: 2026-08-01T17:00:00.000Z
+team: Platform
+storyPoints: 2
+needsDesign: false
+tags:
+  - Small
+---
+
+# Rotate API Keys
+
+Quarterly rotation of all outbound integration keys.

package/example/advanced/.kanbn/tasks/split-billing-service.md

@@ -0,0 +1,17 @@
+---
+created: 2026-06-20T09:00:00.000Z
+updated: 2026-07-10T09:00:00.000Z
+started: 2026-07-05T09:00:00.000Z
+assigned: Ben
+progress: 0.4
+due: 2026-10-01T17:00:00.000Z
+team: Platform
+storyPoints: 8
+needsDesign: false
+tags:
+  - Large
+---
+
+# Split Billing Service
+
+Extract billing out of the monolith into its own service.

package/example/advanced/.kanbn/tasks/upgrade-node-runtime.md

@@ -0,0 +1,19 @@
+---
+created: 2026-06-01T09:00:00.000Z
+updated: 2026-06-18T09:00:00.000Z
+started: 2026-06-05T09:00:00.000Z
+completed: 2026-06-18T09:00:00.000Z
+reviewedAt: 2026-06-15T09:00:00.000Z
+assigned: Ben
+progress: 1
+due: 2026-06-20T17:00:00.000Z
+team: Platform
+storyPoints: 3
+needsDesign: false
+tags:
+  - Medium
+---
+
+# Upgrade Node Runtime
+
+Move all services onto the current Node LTS release.

package/example/advanced/kanbn.yml

@@ -0,0 +1,59 @@
+# All project options for this board live in this file instead of the index front matter.
+# Kanbn looks for `kanbn.json` or `kanbn.yml` in the root of the workspace.
+#
+# Note: Kanbn rewrites this file whenever it saves project options (for example
+# `kanbn sort --save`), which strips these comments.
+
+startedColumns:
+  - 'In Progress'
+  - Review
+completedColumns:
+  - Done
+
+# The Blocked column is hidden from the default board, but still tracked.
+# Any view that defines its own columns can still show it.
+hiddenColumns:
+  - Blocked
+
+defaultTaskWorkload: 2
+taskWorkloadTags:
+  Tiny: 1
+  Small: 2
+  Medium: 3
+  Large: 5
+  Huge: 8
+
+# Extra metadata fields. Once declared here they can be set with `kanbn add`
+# and `kanbn edit`, searched with `kanbn find`, sorted with `kanbn sort`,
+# filtered in views, and interpolated into taskTemplate.
+customFields:
+  - name: team
+    type: string
+  - name: storyPoints
+    type: number
+  - name: needsDesign
+    type: boolean
+  - name: reviewedAt
+    type: date
+    updateDate: once
+
+# `reviewedAt` is stamped the first time a task enters the Review column
+# (`updateDate: once`). Use `always` to re-stamp on every move.
+reviewedAtColumns:
+  - Review
+
+# The Backlog column is kept sorted in the index file itself, so the order
+# survives `kanbn add`, `kanbn move` and `kanbn validate --save`.
+columnSorting:
+  Backlog:
+    - field: workload
+      order: descending
+    - field: name
+      order: ascending
+
+dateFormat: yyyy-mm-dd
+
+# 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.
+taskTemplate: "^+^_${overdue ? '^R' : ''}${name}^:${assigned ? ('\\n^-@' + assigned) : ''}${team ? ('\\n^-' + team) : ''}${storyPoints ? ('\\n^-' + storyPoints + 'pts') : ''}${due ? ('\\n^-due ' + due) : ''}"

package/example/views/.kanbn/index.md

@@ -0,0 +1,140 @@
+---
+startedColumns:
+  - 'In Progress'
+completedColumns:
+  - Done
+hiddenColumns:
+  - Icebox
+taskWorkloadTags:
+  Tiny: 1
+  Small: 2
+  Medium: 3
+  Large: 5
+  Huge: 8
+views:
+
+  # The index columns, spelled out explicitly. Note that a view column with no
+  # filters would show *every* task, not the tasks in a column of that name.
+  - name: 'default'
+    columns:
+      - name: 'Backlog'
+        filters:
+          column: 'Backlog'
+      - name: 'In Progress'
+        filters:
+          column: 'In Progress'
+      - name: 'Done'
+        filters:
+          column: 'Done'
+
+  # The same columns, grouped into one lane per assignee.
+  # Lane filters are merged over each column's filters.
+  - name: 'by-assignee'
+    columns:
+      - name: 'Backlog'
+        filters:
+          column: 'Backlog'
+      - name: 'In Progress'
+        filters:
+          column: 'In Progress'
+      - name: 'Done'
+        filters:
+          column: 'Done'
+    lanes:
+      - name: 'Ana'
+        filters:
+          assigned: '^Ana$'
+      - name: 'Ben'
+        filters:
+          assigned: '^Ben$'
+      - name: 'Unassigned'
+        filters:
+          assigned: '^$'
+
+  # A root filter narrows the whole view to bugs before columns are built.
+  # The second column has no filters, so within this view it shows all bugs.
+  - name: 'triage'
+    filters:
+      tag: Bug
+    columns:
+      - name: 'Due before Aug 2026'
+        filters:
+          due:
+            - 2020-01-01
+            - 2026-08-01
+        sorters:
+          - field: workload
+            order: descending
+      - name: 'All bugs'
+        sorters:
+          - field: name
+            order: ascending
+
+  # Columns and lanes don't have to correspond to index columns at all.
+  - name: 'workload'
+    columns:
+      - name: 'Small (1-2)'
+        filters:
+          workload:
+            - 1
+            - 2
+      - name: 'Medium (3-5)'
+        filters:
+          workload:
+            - 3
+            - 5
+      - name: 'Large (6+)'
+        filters:
+          workload:
+            - 6
+            - 99
+    lanes:
+      - name: 'Not started'
+        filters:
+          column: 'Backlog'
+      - name: 'Started'
+        filters:
+          column: 'In Progress'
+
+  # A view that defines its own columns ignores hiddenColumns, so this one
+  # also shows tasks in the hidden Icebox column.
+  - name: 'everything'
+    columns:
+      - name: 'All tasks (including Icebox)'
+        sorters:
+          - field: column
+            order: ascending
+          - field: name
+            order: ascending
+---
+
+# Views Example
+
+A small board used to demonstrate views, lanes, filters and sorters. Try:
+
+- `kanbn board`
+- `kanbn board -v default`
+- `kanbn board -v by-assignee`
+- `kanbn board -v triage`
+- `kanbn board -v workload`
+- `kanbn board -v everything`
+
+## Backlog
+
+- [add-audit-log-export](tasks/add-audit-log-export.md)
+- [fix-avatar-upload-crash](tasks/fix-avatar-upload-crash.md)
+- [rewrite-search-indexer](tasks/rewrite-search-indexer.md)
+- [tidy-up-settings-copy](tasks/tidy-up-settings-copy.md)
+
+## In Progress
+
+- [fix-expired-session-redirect](tasks/fix-expired-session-redirect.md)
+- [build-webhook-retry-queue](tasks/build-webhook-retry-queue.md)
+
+## Done
+
+- [add-dark-mode-toggle](tasks/add-dark-mode-toggle.md)
+
+## Icebox
+
+- [investigate-offline-mode](tasks/investigate-offline-mode.md)

package/example/views/.kanbn/tasks/add-audit-log-export.md

@@ -0,0 +1,18 @@
+---
+created: 2026-07-02T09:00:00.000Z
+updated: 2026-07-02T09:00:00.000Z
+assigned: Ana
+due: 2026-09-30T17:00:00.000Z
+tags:
+  - Feature
+  - Medium
+---
+
+# Add Audit Log Export
+
+Let admins download an audit log as CSV.
+
+## Sub-tasks
+
+- [ ] Add an export endpoint
+- [ ] Add a download button to the audit log page

package/example/views/.kanbn/tasks/add-dark-mode-toggle.md

@@ -0,0 +1,16 @@
+---
+created: 2026-06-20T09:00:00.000Z
+updated: 2026-07-01T09:00:00.000Z
+started: 2026-06-22T09:00:00.000Z
+completed: 2026-07-01T09:00:00.000Z
+assigned: Ana
+progress: 1
+due: 2026-07-01T17:00:00.000Z
+tags:
+  - Feature
+  - Small
+---
+
+# Add Dark Mode Toggle
+
+Add a dark mode toggle to the account menu.