Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(kanban): lifecycle category on columns

review8080d380b089
diff --git a/src/core/project-kanban-write.labels.test.ts b/src/core/project-kanban-write.labels.test.ts
index f67610883..d8bfcccca 100644
--- a/src/core/project-kanban-write.labels.test.ts
+++ b/src/core/project-kanban-write.labels.test.ts
@@ -113,6 +113,9 @@ describe('editProjectCardLabels — the first label seeds the board', () => {
editProjectCardLabels(file(), 'term-a', edit({ create: [{ name: 'bug', color: 'red' }] }), NOW, () => 'kcol-x')
)
expect(out.kanban.columns.map((c: { title: string }) => c.title)).toEqual(DEFAULT_BOARD_COLUMNS.map((c) => c.title))
+ expect(out.kanban.columns.map((c: { category?: string }) => c.category)).toEqual(
+ DEFAULT_BOARD_COLUMNS.map((c) => c.category)
+ )
expect(out.kanban.assignments).toEqual([])
expect(labelsForCard(out.kanban, 'term-a').map((l) => l.name)).toEqual(['bug'])
})
diff --git a/src/core/project-kanban-write.test.ts b/src/core/project-kanban-write.test.ts
index f70bc55ef..73fb6855c 100644
--- a/src/core/project-kanban-write.test.ts
+++ b/src/core/project-kanban-write.test.ts
@@ -32,6 +32,15 @@ describe('ensureProjectBoard', () => {
expect(out.savedAt).toBe(NOW.toISOString())
})
+ it('seeds the lifecycle category the desktop default carries (a phone-born board is the same board)', () => {
+ const out = parse(ensureProjectBoard(file(), NOW, () => 'kcol-fixed'))
+ expect(out.kanban.columns.map((c: { category?: string }) => c.category)).toEqual([
+ 'unstarted',
+ 'started',
+ 'done'
+ ])
+ })
+
it('mints a distinct id per column, in the desktop shape', () => {
const out = parse(ensureProjectBoard(file(), NOW))
const ids: string[] = out.kanban.columns.map((c: { id: string }) => c.id)
diff --git a/src/core/project-kanban-write.ts b/src/core/project-kanban-write.ts
index d66e2595b..97ae7b642 100644
--- a/src/core/project-kanban-write.ts
+++ b/src/core/project-kanban-write.ts
@@ -13,7 +13,7 @@
// parse must never be invented or overwritten), or a request that is already satisfied (a board that
// exists, a card already in that column) — a retry must not churn `rev`.
-import { DEFAULT_BOARD_COLUMNS, makeColumnId } from '../shared/kanban-default-board'
+import { defaultBoardColumns, makeColumnId } from '../shared/kanban-default-board'
import {
KANBAN_LABEL_COLORS,
boardLabels,
@@ -73,7 +73,7 @@ export function ensureProjectBoard(raw: string, now: Date, mintId = makeColumnId
const board = boardOf(root)
if (!board) return null
if (columnsOf(board).length > 0) return null
- board.columns = DEFAULT_BOARD_COLUMNS.map((c) => ({ id: mintId(), title: c.title, color: c.color }))
+ board.columns = defaultBoardColumns(mintId)
if (!Array.isArray(board.assignments)) board.assignments = []
root.kanban = board
return bumped(root, now)
@@ -255,7 +255,7 @@ export function editProjectCardLabels(
const next = k as unknown as Record<string, unknown>
if (columnsOf(next).length === 0) {
- next.columns = DEFAULT_BOARD_COLUMNS.map((c) => ({ id: mintId(), title: c.title, color: c.color }))
+ next.columns = defaultBoardColumns(mintId)
}
if (!Array.isArray(next.assignments)) next.assignments = []
root.kanban = next
diff --git a/src/core/workspace-files.test.ts b/src/core/workspace-files.test.ts
index 0f6657786..6b5c86a72 100644
--- a/src/core/workspace-files.test.ts
+++ b/src/core/workspace-files.test.ts
@@ -1,8 +1,8 @@
import { describe, it, expect } from 'vitest'
-import type { CanvasNodeState, Project, Workspace } from '../shared/types'
+import type { CanvasNodeState, Project, ProjectKanban, Workspace } from '../shared/types'
import {
toPortableNodes, resolveNodes, projectToFile, fileToProject, framingViewport,
- sameProjectContent, splitWorkspace, serializeProjectFile
+ sameProjectContent, splitWorkspace, serializeProjectFile, sanitizeKanban
} from './workspace-files'
import { legacyFileId } from '../shared/project-id'
import { CANVAS_LAYOUTS_CAP, type CanvasLayout } from '../shared/canvas-layout'
@@ -578,6 +578,72 @@ describe('kanban board persistence', () => {
})
})
+describe('sanitizeKanban — the board is hostile, git-shared input', () => {
+ const clean = (): ProjectKanban => ({
+ columns: [
+ { id: 'kcol-a', title: 'To Do', color: '#0a84ff', category: 'unstarted' },
+ { id: 'kcol-b', title: 'Done', color: '#32d74b', category: 'done' }
+ ],
+ assignments: [{ nodeId: 'term-abc', columnId: 'kcol-b' }]
+ })
+
+ it('returns a clean board BY IDENTITY (no churn on a well-formed file)', () => {
+ const k = clean()
+ expect(sanitizeKanban(k)).toBe(k)
+ })
+
+ it('rejects what validKanban rejects', () => {
+ expect(sanitizeKanban(undefined)).toBeUndefined()
+ expect(sanitizeKanban({ columns: [], cards: [] })).toBeUndefined()
+ expect(sanitizeKanban('nope')).toBeUndefined()
+ })
+
+ it('keeps an UNKNOWN category string (a newer build\'s value must survive our save)', () => {
+ const k = { ...clean(), columns: [{ id: 'kcol-a', title: 'To Do', color: '#fff', category: 'blocked' }] }
+ expect(sanitizeKanban(k)?.columns[0]).toEqual({ id: 'kcol-a', title: 'To Do', color: '#fff', category: 'blocked' })
+ })
+
+ it('drops a NON-string category without throwing, keeping the column', () => {
+ const k = { ...clean(), columns: [{ id: 'kcol-a', title: 'To Do', color: '#fff', category: { evil: 1 } }] }
+ expect(sanitizeKanban(k)?.columns).toEqual([{ id: 'kcol-a', title: 'To Do', color: '#fff' }])
+ })
+
+ it('drops column entries a renderer would crash on (non-object, missing id/title)', () => {
+ const k = {
+ columns: [null, 42, { id: 'x' }, { title: 'no id' }, { id: 'ok', title: { oops: 1 } }, clean().columns[0]],
+ assignments: []
+ }
+ expect(sanitizeKanban(k)?.columns).toEqual([clean().columns[0]])
+ })
+
+ it('drops malformed assignments and keeps the rest', () => {
+ const k = { ...clean(), assignments: [null, { nodeId: 1, columnId: 'kcol-a' }, { nodeId: 'n' }, { nodeId: 'n', columnId: 'kcol-a' }] }
+ expect(sanitizeKanban(k)?.assignments).toEqual([{ nodeId: 'n', columnId: 'kcol-a' }])
+ })
+
+ it('keeps fields it does not know (a newer build\'s board data round-trips)', () => {
+ const k = { ...clean(), futureThing: [1, 2], columns: [{ ...clean().columns[0], wip: 3 }] }
+ const out = sanitizeKanban(k) as unknown as Record<string, unknown>
+ expect(out.futureThing).toEqual([1, 2])
+ expect((out.columns as Array<Record<string, unknown>>)[0].wip).toBe(3)
+ })
+
+ it('runs on the READ seam (fileToProject)', () => {
+ const f = projectToFile(project(), 1, '2026-07-18T00:00:00.000Z')
+ const evil = { ...f, kanban: { columns: [null, { id: 'a', title: 'A', color: '#fff', category: 7 }], assignments: [] } }
+ expect(fileToProject(evil as unknown as ProjectFileV1, { id: 'p1' }).kanban).toEqual({
+ columns: [{ id: 'a', title: 'A', color: '#fff' }],
+ assignments: []
+ })
+ })
+
+ it('runs on the WRITE seam (projectToFile) — live data reached by a peer is not trusted either', () => {
+ const live = { columns: [{ id: 'a', title: 'A', color: '#fff', category: [] }], assignments: [7] }
+ const f = projectToFile(project({ kanban: live as unknown as ProjectKanban }), 1, 'now')
+ expect(f.kanban).toEqual({ columns: [{ id: 'a', title: 'A', color: '#fff' }], assignments: [] })
+ })
+})
+
describe('the shared file carries content, not machine identity', () => {
const p = project({
id: 'project-mridky20-11', cwd: '/a/foo', name: 'shared', defaultAccountId: 'acct-1',
diff --git a/src/core/workspace-files.ts b/src/core/workspace-files.ts
index 02b037103..eda8992a5 100644
--- a/src/core/workspace-files.ts
+++ b/src/core/workspace-files.ts
@@ -362,6 +362,8 @@ export function projectToFile(
// as IN. Validating one direction only passes every round-trip test while leaving the other one
// open. See @shared/canvas-layout.
const layouts = sanitizeLayouts(p.layouts)
+ // Same two-seam rule for the board (see `sanitizeKanban`).
+ const kanban = p.kanban ? sanitizeKanban(p.kanban) : undefined
return {
version: 1,
rev,
@@ -380,7 +382,7 @@ export function projectToFile(
// the acknowledgment is machine-local (IndexEntryV3.capabilityAck) and must never travel.
...projectCapabilityFields(p),
...(p.dinoHighScore ? { dinoHighScore: p.dinoHighScore } : {}),
- ...(p.kanban ? { kanban: p.kanban } : {}),
+ ...(kanban ? { kanban } : {}),
// `layoutViewports` is deliberately absent: a field of that name in the shared file is a
// forgery (a repo carrying one person's camera), and `fileToProject` never reads one.
...(layouts ? { layouts } : {})
@@ -399,6 +401,52 @@ export function validKanban(k: unknown): k is ProjectKanban {
)
}
+const isRecord = (x: unknown): x is Record<string, unknown> =>
+ !!x && typeof x === 'object' && !Array.isArray(x)
+
+/**
+ * The board as it may be ADMITTED: `validKanban`'s shape rule plus the per-entry repairs a
+ * hand-edited, git-shared file needs before a renderer touches it — a render throw on a bad board
+ * boot-loops the app (the board view choice persists in localStorage).
+ *
+ * Repairs, never inventions:
+ * - a column that is not an object with a string `id` and `title` is dropped (React cannot render
+ * an object title, and `resolveColumnRef` lower-cases it);
+ * - a column's `category` that is not a STRING is dropped. An unknown string is KEPT: it may be a
+ * category a newer build added, and dropping it here would erase that build's data from the
+ * shared file on our next save. Readers treat it as absent (`columnCategory`);
+ * - an assignment that is not an object with string `nodeId` and `columnId` is dropped.
+ * Every other field — known or not — round-trips untouched.
+ *
+ * Returns the SAME object when nothing needed repair, so a clean file is never rewritten, and
+ * `undefined` for anything `validKanban` refuses. Used on every seam: `fileToProject` (in),
+ * `projectToFile` (out), and the inline-project branch of the store, which bypasses both.
+ */
+export function sanitizeKanban(k: unknown): ProjectKanban | undefined {
+ if (!validKanban(k)) return undefined
+ let changed = false
+ const columns: ProjectKanban['columns'] = []
+ for (const c of k.columns as unknown[]) {
+ if (!isRecord(c) || typeof c.id !== 'string' || typeof c.title !== 'string') {
+ changed = true
+ continue
+ }
+ if ('category' in c && typeof c.category !== 'string') {
+ const { category: _drop, ...rest } = c
+ columns.push(rest as unknown as ProjectKanban['columns'][number])
+ changed = true
+ continue
+ }
+ columns.push(c as unknown as ProjectKanban['columns'][number])
+ }
+ const assignments = (k.assignments as unknown[]).filter(
+ (a): a is ProjectKanban['assignments'][number] =>
+ isRecord(a) && typeof a.nodeId === 'string' && typeof a.columnId === 'string'
+ )
+ if (assignments.length !== k.assignments.length) changed = true
+ return changed ? { ...k, columns, assignments } : k
+}
+
/** A `{x, y}` point, checked at the boundary because the file is hostile input. */
function validPoint(p: unknown): p is { x: number; y: number } {
return (
@@ -511,6 +559,7 @@ export function fileToProject(
// (they are shared content, the cameras are not), or a hand edit dropped it. Pruning on the way
// in as well as out is what stops workspace.json accumulating orphans forever.
const layoutViewports = pruneLayoutViewports(base.layoutViewports, layouts)
+ const kanban = sanitizeKanban(f.kanban)
return {
id: base.id,
// A project whose stored name IS its own path is one this machine (or a teammate's) created
@@ -542,7 +591,7 @@ export function fileToProject(
// (readProjectCapabilities). `"true"`, 1, {} et al. vanish here, at the boundary.
...readProjectCapabilities(f),
...(f.dinoHighScore ? { dinoHighScore: f.dinoHighScore } : {}),
- ...(validKanban(f.kanban) ? { kanban: f.kanban } : {}),
+ ...(kanban ? { kanban } : {}),
...(base.cwd ? { cwd: base.cwd } : {}),
...(base.ssh ? { ssh: base.ssh } : {}),
...(base.closed ? { closed: true } : {}),
diff --git a/src/core/workspace-store.test.ts b/src/core/workspace-store.test.ts
index 5c1e51b97..67691550e 100644
--- a/src/core/workspace-store.test.ts
+++ b/src/core/workspace-store.test.ts
@@ -233,6 +233,18 @@ describe('inline (cwd-less) project kanban shape guard', () => {
const loaded = await new WorkspaceStore().load()
expect(loaded.projects[0].kanban).toEqual(board)
})
+
+ it('sanitizes an inline board like a file one (the inline branch bypasses fileToProject)', async () => {
+ await writeInlineIndex({
+ columns: [null, { id: 'kcol-a', title: 'To Do', color: '#0a84ff', category: 5 }],
+ assignments: [{ nodeId: 3 }]
+ })
+ const loaded = await new WorkspaceStore().load()
+ expect(loaded.projects[0].kanban).toEqual({
+ columns: [{ id: 'kcol-a', title: 'To Do', color: '#0a84ff' }],
+ assignments: []
+ })
+ })
})
describe('one-time exec migration (pre-existing project files)', () => {
diff --git a/src/core/workspace-store.ts b/src/core/workspace-store.ts
index 767ec1791..a7e00be02 100644
--- a/src/core/workspace-store.ts
+++ b/src/core/workspace-store.ts
@@ -13,7 +13,7 @@ import {
PROJECT_DIR, PROJECT_FILE, fileToProject, inlineProjectFileRelPath, isInlineProjectFileId,
projectToFile, resolveNodes, sameProjectContent,
sanitizeLoadedClosedSessions, sanitizeNodeTriggers, serializeProjectFile, splitWorkspace,
- validKanban,
+ sanitizeKanban,
type IndexEntryV3, type ProjectFileV1, type WorkspaceIndexV3
} from './workspace-files'
import { readProjectSettingsFile, writeProjectSettingsFile } from './project-settings-files'
@@ -333,7 +333,8 @@ export class WorkspaceStore {
// and the same trigger shape rule (workspace.json is hand-editable input too).
// `rest` drops BOTH guarded fields; each is added back below only if it passes its guard.
const { kanban, closedSessions, layouts, layoutViewports, ...rest } = e.project
- const base = validKanban(kanban) ? { ...rest, kanban } : rest
+ const admittedKanban = sanitizeKanban(kanban)
+ const base = admittedKanban ? { ...rest, kanban: admittedKanban } : rest
// An inline project's embedded layouts are hand-editable input exactly like a git-shared
// file's, and they never pass through `fileToProject` on this branch, so they are
// sanitized (and their cameras pruned against them) here instead.
diff --git a/src/renderer/components/kanban/KanbanColumn.tsx b/src/renderer/components/kanban/KanbanColumn.tsx
index cf874cfe7..c239abba9 100644
--- a/src/renderer/components/kanban/KanbanColumn.tsx
+++ b/src/renderer/components/kanban/KanbanColumn.tsx
@@ -1,8 +1,10 @@
import { Fragment, memo, useLayoutEffect, useRef, useState } from 'react'
import { createPortal } from 'react-dom'
import { IconClose } from '../icons'
-import type { KanbanColumn as KanbanColumnT } from '@shared/types'
+import type { KanbanColumn as KanbanColumnT, KanbanColumnCategory } from '@shared/types'
import { SYSTEM_NODE_COLOR_SWATCHES } from '@shared/node-colors'
+import { CATEGORY_LABELS, KANBAN_COLUMN_CATEGORIES, columnCategory } from '@shared/kanban-category'
+import { ContextMenu, type MenuItem } from '../ContextMenu'
import type { KanbanCreateChoice, KanbanCreateOption } from './KanbanView'
import { byLane, type KanbanSourceId } from '../../lib/kanbanSources'
@@ -30,6 +32,10 @@ interface KanbanColumnProps {
onRename?: (columnId: string, title: string) => void
onRecolor?: (columnId: string, color: string) => void
onDelete?: (columnId: string) => void
+ /** Set (or clear, with `undefined`) the column's lifecycle category. Absent = no column menu
+ * (the Ungrouped column, a board surface that does not edit categories). The BOARD decides
+ * whether the change needs confirming; the column only reports what was picked. */
+ onSetCategory?: (columnId: string, category: KanbanColumnCategory | undefined) => void
/** "+ New" menu entries (agents, terminal, sticky) and what to do when one is picked
* (columnId null = Ungrouped: no assignment). */
createOptions: KanbanCreateOption[]
@@ -42,9 +48,10 @@ interface KanbanColumnProps {
}
export const KanbanColumn = memo(function KanbanColumn({
- column, lanes, onRename, onRecolor, onDelete,
+ column, lanes, onRename, onRecolor, onDelete, onSetCategory,
createOptions, onCreate, onColumnDragStart, onDragEnd, onDropOnColumn
}: KanbanColumnProps) {
+ const [columnMenu, setColumnMenu] = useState<{ x: number; y: number } | null>(null)
const [editingTitle, setEditingTitle] = useState(false)
const [title, setTitle] = useState(column?.title ?? '')
const [swatchesOpen, setSwatchesOpen] = useState(false)
@@ -96,7 +103,23 @@ export const KanbanColumn = memo(function KanbanColumn({
}, [newMenuOpen])
const colId = column?.id ?? null
+ const category = columnCategory(column)
const orderedLanes = byLane(lanes)
+ // The column menu: the lifecycle category (a closed set) as check rows, current one ticked.
+ const menuItems = (): MenuItem[] => {
+ if (!column || !onSetCategory) return []
+ const pick = (next: KanbanColumnCategory | undefined): MenuItem => ({
+ label: next ? CATEGORY_LABELS[next] : 'No category',
+ icon: category === next ? <span aria-label="current">✓</span> : undefined,
+ onClick: () => onSetCategory(column.id, next)
+ })
+ return [
+ { type: 'label', label: 'Category' },
+ ...KANBAN_COLUMN_CATEGORIES.map(pick),
+ { type: 'separator' },
+ pick(undefined)
+ ]
+ }
const count = lanes.reduce((total, lane) => total + lane.count, 0)
const commitTitle = () => {
@@ -126,6 +149,11 @@ export const KanbanColumn = memo(function KanbanColumn({
onColumnDragStart?.(column.id)
}}
onDragEnd={onDragEnd}
+ onContextMenu={(e) => {
+ if (!column || !onSetCategory) return
+ e.preventDefault()
+ setColumnMenu({ x: e.clientX, y: e.clientY })
+ }}
>
{column ? (
<button
@@ -161,7 +189,28 @@ export const KanbanColumn = memo(function KanbanColumn({
{column ? column.title : 'Ungrouped'}
</span>
)}
+ {category && (
+ <span
+ className={`kanban-col__category kanban-col__category--${category}`}
+ title={`Lifecycle category: ${CATEGORY_LABELS[category]}`}
+ >
+ {CATEGORY_LABELS[category]}
+ </span>
+ )}
<span className="kanban-col__count">{count}</span>
+ {column && onSetCategory && (
+ <button
+ className="kanban-col__menu"
+ title="Column options"
+ aria-label="Column options"
+ onClick={(e) => {
+ const r = (e.currentTarget as HTMLElement).getBoundingClientRect()
+ setColumnMenu({ x: r.left, y: r.bottom + 4 })
+ }}
+ >
+ ⋯
+ </button>
+ )}
{column && (
<button
className="kanban-col__close"
@@ -172,6 +221,15 @@ export const KanbanColumn = memo(function KanbanColumn({
</button>
)}
</div>
+ {columnMenu && column && onSetCategory && (
+ <ContextMenu
+ x={columnMenu.x}
+ y={columnMenu.y}
+ zIndex={60}
+ items={menuItems()}
+ onClose={() => setColumnMenu(null)}
+ />
+ )}
{column && swatchesOpen && (
<div className="kanban-col__swatches">
{/* System subset, not the agent colors: ColumnPill draws a column's color as 10px
diff --git a/src/renderer/components/kanban/KanbanView.category.test.tsx b/src/renderer/components/kanban/KanbanView.category.test.tsx
new file mode 100644
index 000000000..96c1dbe38
--- /dev/null
+++ b/src/renderer/components/kanban/KanbanView.category.test.tsx
@@ -0,0 +1,187 @@
+// @vitest-environment jsdom
+//
+// Column lifecycle categories on the board: the progress readout, hiding `closed` columns behind a
+// per-user toggle, and the rule that a category is never changed SILENTLY under cards.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { KanbanView, type KanbanSession } from './KanbanView'
+import type { ProjectKanban } from '@shared/types'
+import { useKanbanDisplay } from '../../state/kanbanDisplay'
+import { useProjects } from '../../state/projects'
+
+vi.mock('../../session/session', () => ({
+ useSession: () => ({ source: 'local', api: window.nodeTerminal })
+}))
+
+let root: Root
+let host: HTMLElement
+const card = (id: string): KanbanSession =>
+ ({ id, title: `Card ${id}`, color: '#fff', kind: 'terminal', spawn: {} }) as unknown as KanbanSession
+
+const board = (): ProjectKanban => ({
+ columns: [
+ { id: 'todo', title: 'To Do', color: '#0a84ff', category: 'unstarted' },
+ { id: 'review', title: 'Review', color: '#ffd60a', category: 'started' },
+ { id: 'done', title: 'Done', color: '#32d74b', category: 'done' },
+ { id: 'wontfix', title: "Won't fix", color: '#8e8e93', category: 'closed' },
+ { id: 'empty', title: 'Empty', color: '#bf5af2' }
+ ],
+ assignments: [
+ { nodeId: 'a', columnId: 'todo' },
+ { nodeId: 'b', columnId: 'review' },
+ { nodeId: 'c', columnId: 'done' },
+ { nodeId: 'd', columnId: 'wontfix' }
+ ]
+})
+
+beforeEach(() => {
+ vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+ vi.stubGlobal(
+ 'ResizeObserver',
+ class {
+ observe(): void {}
+ unobserve(): void {}
+ disconnect(): void {}
+ }
+ )
+ ;(window as unknown as { nodeTerminal: unknown }).nodeTerminal = {
+ boardLog: { list: async () => [], onChanged: () => () => {} },
+ settings: { save: async () => {} }
+ }
+ useProjects.setState({ activeProjectId: 'p-cat' } as never)
+ useKanbanDisplay.setState({ byProject: {} })
+})
+afterEach(() => {
+ act(() => root.unmount())
+ host.remove()
+ document.body.innerHTML = ''
+ vi.unstubAllGlobals()
+})
+
+function render(k: ProjectKanban, onChange = vi.fn(), sessions = ['a', 'b', 'c', 'd', 'e'].map(card)) {
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+ const noop = (): void => {}
+ const el = (b: ProjectKanban) => (
+ <KanbanView
+ board={b}
+ sessions={sessions}
+ onChange={onChange}
+ onOpenNode={noop}
+ onCreateNode={noop}
+ onRenameNode={noop}
+ onEditSticky={noop}
+ onDeleteNode={noop}
+ onModalNodeChange={noop}
+ onBrowserNav={noop}
+ onSetIcon={noop}
+ />
+ )
+ act(() => root.render(el(k)))
+ return { onChange, rerender: (b: ProjectKanban) => act(() => root.render(el(b))) }
+}
+
+const columnTitles = (): string[] =>
+ [...document.querySelectorAll('.kanban-col__title')].map((el) => el.textContent ?? '')
+
+const click = (el: Element | null | undefined): void => {
+ if (!el) throw new Error('missing element')
+ act(() => {
+ el.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+ })
+}
+
+function openColumnMenu(title: string): void {
+ const col = [...document.querySelectorAll('.kanban-col')].find(
+ (c) => c.querySelector('.kanban-col__title')?.textContent === title
+ )
+ click(col?.querySelector('.kanban-col__menu'))
+}
+
+const menuRow = (label: string): Element | undefined =>
+ [...document.querySelectorAll('.ctx-item')].find((el) => el.textContent?.includes(label))
+
+describe('KanbanView — lifecycle progress', () => {
+ it('reads done+closed over every live card, Ungrouped included', () => {
+ render(board())
+ // c (done) + d (closed) of a,b,c,d,e (e is Ungrouped).
+ expect(document.querySelector('.kanban-progress')?.textContent).toContain('2/5')
+ })
+
+ it('shows nothing when no column says what "complete" means', () => {
+ const k = { ...board(), columns: board().columns.map(({ category: _c, ...c }) => c) }
+ render(k)
+ expect(document.querySelector('.kanban-progress')).toBeNull()
+ })
+})
+
+describe('KanbanView — closed columns', () => {
+ it('are hidden by default, behind a toggle that names how many', () => {
+ render(board())
+ expect(columnTitles()).not.toContain("Won't fix")
+ const toggle = document.querySelector('.kanban-closed-toggle')
+ expect(toggle?.textContent).toContain('1')
+ click(toggle)
+ expect(columnTitles()).toContain("Won't fix")
+ })
+
+ it('the choice is this user’s (localStorage), never a board edit', () => {
+ const { onChange } = render(board())
+ click(document.querySelector('.kanban-closed-toggle'))
+ expect(onChange).not.toHaveBeenCalled()
+ expect(useKanbanDisplay.getState().showClosed('p-cat')).toBe(true)
+ })
+
+ it('offers no toggle on a board with no closed column', () => {
+ render({ ...board(), columns: board().columns.filter((c) => c.category !== 'closed') })
+ expect(document.querySelector('.kanban-closed-toggle')).toBeNull()
+ })
+})
+
+describe('KanbanView — changing a category', () => {
+ it('an EMPTY column changes immediately', () => {
+ const { onChange } = render(board())
+ openColumnMenu('Empty')
+ click(menuRow('Done'))
+ expect(onChange).toHaveBeenCalledTimes(1)
+ const next = onChange.mock.calls[0][0] as ProjectKanban
+ expect(next.columns.find((c) => c.id === 'empty')?.category).toBe('done')
+ })
+
+ it('a column WITH cards asks first, naming the count — never silently re-means its cards', () => {
+ const { onChange } = render(board())
+ openColumnMenu('Review')
+ click(menuRow('Done'))
+ expect(onChange).not.toHaveBeenCalled()
+ const dialog = document.querySelector('.confirm')
+ expect(dialog?.textContent).toContain('1 card')
+ click([...document.querySelectorAll('button')].find((b) => b.textContent === 'Change category'))
+ expect(onChange).toHaveBeenCalledTimes(1)
+ const next = onChange.mock.calls[0][0] as ProjectKanban
+ expect(next.columns.find((c) => c.id === 'review')?.category).toBe('done')
+ })
+
+ it('cancelling the confirmation changes nothing', () => {
+ const { onChange } = render(board())
+ openColumnMenu('Review')
+ click(menuRow('Closed'))
+ click([...document.querySelectorAll('button')].find((b) => b.textContent === 'Cancel'))
+ expect(onChange).not.toHaveBeenCalled()
+ })
+
+ it('the Ungrouped column has no category menu (it is virtual)', () => {
+ render(board())
+ const ungrouped = document.querySelector('.kanban-col--ungrouped')
+ expect(ungrouped?.querySelector('.kanban-col__menu')).toBeNull()
+ })
+
+ it('a categorized column shows its category in the header', () => {
+ render(board())
+ const review = [...document.querySelectorAll('.kanban-col')].find(
+ (c) => c.querySelector('.kanban-col__title')?.textContent === 'Review'
+ )
+ expect(review?.querySelector('.kanban-col__category')?.textContent).toBe('Started')
+ })
+})
diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsx
index f550a72ef..24d8444f4 100644
--- a/src/renderer/components/kanban/KanbanView.tsx
+++ b/src/renderer/components/kanban/KanbanView.tsx
@@ -1,5 +1,9 @@
import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import type { KanbanLabel, ProjectKanban } from '@shared/types'
+import type { KanbanColumnCategory, KanbanLabel, ProjectKanban } from '@shared/types'
+import {
+ boardProgress, categoryChangeImpact, categoryChangeMessage, columnCategory
+} from '@shared/kanban-category'
+import { useKanbanDisplay } from '../../state/kanbanDisplay'
import type { NodeIcon } from '@shared/node-icon'
import { AGENT_CONFIG, BUILTIN_AGENT_IDS, type AgentId } from '@shared/agents/config'
import { useViewMode } from '../../state/viewMode'
@@ -9,7 +13,7 @@ import { useBoardWallpaperStyle } from '../../state/wallpaper'
import {
addColumn, assignNode, assignedTo, boardLabels, cardMatchesLabelFilter, cardMeta, columnForNode,
deleteColumn, labelsForCard, moveColumn,
- nextColumnColor, pruneAssignments, recolorColumn, renameColumn, unassigned
+ nextColumnColor, pruneAssignments, recolorColumn, renameColumn, setColumnCategory, unassigned
} from '../../lib/kanban'
import { markCanvasCovered } from '../../lib/canvasCovered'
import { labelSwatch } from '../../lib/kanbanLabelColors'
@@ -169,6 +173,13 @@ export const KanbanView = memo(function KanbanView({
const projectId = useProjects((s) => s.activeProjectId)
const projectName = useProjects((s) => s.projects.find((p) => p.id === s.activeProjectId)?.name)
const projectColor = useProjects((s) => s.projects.find((p) => p.id === s.activeProjectId)?.color)
+ // Per-user display: whether `closed` columns are on screen (localStorage, never the board).
+ const showClosed = useKanbanDisplay((s) => s.byProject[projectId]?.showClosed === true)
+ const setShowClosed = useKanbanDisplay((s) => s.setShowClosed)
+ // A category change that would re-mean cards waits here for an explicit confirmation.
+ const [pendingCategory, setPendingCategory] = useState<
+ { columnId: string; category: KanbanColumnCategory | undefined; message: string } | null
+ >(null)
const github = useGitHubIssues((state) => state.projects[projectId])
const githubReadOnly = Object.values(github?.pages ?? {}).some((page) => page.readOnly)
// Pull requests are evicted first when a repository outgrows the cache bounds, so the lane can
@@ -391,6 +402,18 @@ export const KanbanView = memo(function KanbanView({
}
}, [board, byId, sessionIds, activeLocalFilter])
+ // Lifecycle: the board's progress (null when no column says what "complete" means) and the
+ // columns this user sees — `closed` ones only when they asked for them.
+ const progress = useMemo(() => boardProgress(board, sessionIds), [board, sessionIds])
+ const closedCount = useMemo(
+ () => board.columns.filter((c) => columnCategory(c) === 'closed').length,
+ [board.columns]
+ )
+ const shownColumns = useMemo(
+ () => (showClosed ? board.columns : board.columns.filter((c) => columnCategory(c) !== 'closed')),
+ [board.columns, showClosed]
+ )
+
// Stable column/card plumbing — every handler the memoized columns receive is identity-stable
// across renders (the column binds its own id; cards bind theirs).
const handleCardDragStart = useCallback((id: string) => {
@@ -421,6 +444,21 @@ export const KanbanView = memo(function KanbanView({
(columnId: string) => commit(deleteColumn(board, columnId)),
[board, commit]
)
+ // A category is a claim about every card in the column, so a change that would re-mean cards is
+ // never applied silently: an empty column changes at once, a populated one asks first.
+ const handleSetCategory = useCallback(
+ (columnId: string, category: KanbanColumnCategory | undefined) => {
+ const impact = categoryChangeImpact(board, columnId, category, sessionIds)
+ if (!impact) {
+ const next = setColumnCategory(board, columnId, category)
+ if (next !== board) commit(next)
+ return
+ }
+ const title = board.columns.find((c) => c.id === columnId)?.title ?? 'this column'
+ setPendingCategory({ columnId, category, message: categoryChangeMessage(title, impact, !showClosed) })
+ },
+ [board, commit, sessionIds, showClosed]
+ )
const handleMoveGitHub = requestGitHubMove
const githubPage = useCallback((columnId: string | null) =>
github?.pages[columnId ?? 'ungrouped'], [github])
@@ -563,6 +601,30 @@ export const KanbanView = memo(function KanbanView({
<div className="kanban-header">
<span className="kanban-header__dot" style={{ background: projectColor }} />
<span className="kanban-header__name">{projectName}</span>
+ {progress && (
+ <span
+ className="kanban-progress"
+ title="Cards in Done and Closed columns, out of every card on the board"
+ >
+ <span className="kanban-progress__bar">
+ <span
+ className="kanban-progress__fill"
+ style={{ width: `${Math.round((progress.complete / progress.total) * 100)}%` }}
+ />
+ </span>
+ {progress.complete}/{progress.total} done
+ </span>
+ )}
+ {closedCount > 0 && (
+ <button
+ className={`kanban-filter-btn kanban-closed-toggle${showClosed ? ' kanban-filter-btn--on' : ''}`}
+ title={showClosed ? 'Hide closed columns' : 'Show closed columns'}
+ aria-pressed={showClosed}
+ onClick={() => setShowClosed(projectId, !showClosed)}
+ >
+ {showClosed ? 'Hide closed' : `Show closed · ${closedCount}`}
+ </button>
+ )}
{board.github && <KanbanSourceFilter value={source} onChange={setSource} />}
{board.github && github?.loading && <span className="kanban-github-status">Loading GitHub issues…</span>}
{board.github && github?.error && (
@@ -645,7 +707,7 @@ export const KanbanView = memo(function KanbanView({
onDragEnd={handleDragEnd}
onDropOnColumn={dropOnColumn}
/>
- {board.columns.map((col) => (
+ {shownColumns.map((col) => (
<KanbanColumn
key={col.id}
column={col}
@@ -653,6 +715,7 @@ export const KanbanView = memo(function KanbanView({
onRename={handleRenameColumn}
onRecolor={handleRecolorColumn}
onDelete={handleDeleteColumn}
+ onSetCategory={handleSetCategory}
createOptions={createOptions}
onCreate={onCreateNode}
onColumnDragStart={handleColumnDragStart}
@@ -706,6 +769,19 @@ export const KanbanView = memo(function KanbanView({
onClose={() => setModalIssue(null)}
/>
)}
+ {pendingCategory && (
+ <ConfirmDialog
+ message={pendingCategory.message}
+ confirmLabel="Change category"
+ onCancel={() => setPendingCategory(null)}
+ onConfirm={() => {
+ const { columnId, category } = pendingCategory
+ setPendingCategory(null)
+ const next = setColumnCategory(board, columnId, category)
+ if (next !== board) commit(next)
+ }}
+ />
+ )}
{pendingGitHubMove && (
<ConfirmDialog
message={pendingGitHubMove.confirmation.message}
diff --git a/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx b/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx
index cc5bf45ab..a924d942f 100644
--- a/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx
+++ b/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx
@@ -169,6 +169,30 @@ describe('GitHubIssuesSection', () => {
+ // Before lifecycle categories the default was simply the LAST column; a board with an archive
+ // column after Done would then close issues into the archive.
+ it('defaults the completion column to the board\'s Done-category column, not merely the last one', async () => {
+ useProjects.setState({
+ activeProjectId: 'p1',
+ projects: [{
+ id: 'p1', name: 'Project', color: '#8b5cf6', viewport: { x: 0, y: 0, zoom: 1 },
+ nodes: [], cwd: '/repo',
+ kanban: {
+ columns: [
+ { id: 'todo', title: 'Todo', color: '#2563eb', category: 'unstarted' },
+ { id: 'shipped', title: 'Shipped', color: '#16a34a', category: 'done' },
+ { id: 'archive', title: 'Archive', color: '#8e8e93', category: 'closed' }
+ ],
+ assignments: []
+ }
+ }]
+ })
+ await mount()
+ const toggle = host.querySelector<HTMLElement>('[aria-label="Include GitHub issues"]')!
+ await act(async () => { toggle.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+ expect(useProjects.getState().getProject('p1')?.kanban?.github?.completionColumnId).toBe('shipped')
+ })
+
it('reports an Approve failure beside the Approve button, not three rows below it', async () => {
;(window as unknown as { nodeTerminal: any }).nodeTerminal.githubControl.approve =
vi.fn(async () => { throw Object.assign(new Error('invalid-configuration'), { code: 'invalid-configuration' }) })
diff --git a/src/renderer/components/settings/sections/GitHubIssuesSection.tsx b/src/renderer/components/settings/sections/GitHubIssuesSection.tsx
index f9b62dbd3..4889bf39b 100644
--- a/src/renderer/components/settings/sections/GitHubIssuesSection.tsx
+++ b/src/renderer/components/settings/sections/GitHubIssuesSection.tsx
@@ -5,6 +5,8 @@ import type {
GitHubControlView,
ProjectKanbanGitHub
} from '@shared/github-issues'
+import type { KanbanColumn } from '@shared/types'
+import { defaultCompletionColumnId } from '@shared/kanban-category'
import { useProjects } from '../../../state/projects'
import { markWorkspaceDirty } from '../../../state/workspaceDirty'
import { SettingsSection } from '../SettingsSection'
@@ -45,13 +47,16 @@ const ENTRIES = Object.values(ROWS)
type Confirmation = 'labels' | 'cache' | 'revoke' | null
type NoticeRow = 'repository' | 'authentication' | 'data'
-function defaultGitHub(columns: Array<{ id: string; title: string }>): ProjectKanbanGitHub {
+function defaultGitHub(columns: Array<Pick<KanbanColumn, 'id' | 'title' | 'category'>>): ProjectKanbanGitHub {
+ // The board's own Done column when its categories say which one that is; the last column only
+ // for an uncategorized board (the pre-category default). See @shared/kanban-category.
+ const completionColumnId = defaultCompletionColumnId(columns)
return {
columnMappings: columns.map((column) => ({
columnId: column.id,
label: `status:${column.title.trim().toLocaleLowerCase('en-US').replace(/\s+/g, '-')}`
})),
- ...(columns.length ? { completionColumnId: columns[columns.length - 1].id } : {})
+ ...(completionColumnId ? { completionColumnId } : {})
}
}
diff --git a/src/renderer/lib/kanban.test.ts b/src/renderer/lib/kanban.test.ts
index 2feae223c..853fd0e62 100644
--- a/src/renderer/lib/kanban.test.ts
+++ b/src/renderer/lib/kanban.test.ts
@@ -6,7 +6,8 @@ import {
setCardDue, setCardPriority, toggleAssignee, unassigned,
boardLabels, cardMatchesLabelFilter, createLabel, deleteLabel, labelColor, labelsForCard,
recolorLabel, renameLabel, reorderLabels, toggleCardLabel,
- autoLabelColor, migrateProjectTags, migrateTagsToLabels, setCardLabels, resolveColumnRef
+ autoLabelColor, migrateProjectTags, migrateTagsToLabels, setCardLabels, resolveColumnRef,
+ setColumnCategory
} from './kanban'
import type { Project } from '@shared/types'
@@ -26,6 +27,7 @@ describe('defaultKanban', () => {
it('makes To Do / In Progress / Done with unique ids and no assignments', () => {
const k = defaultKanban()
expect(k.columns.map((c) => c.title)).toEqual(['To Do', 'In Progress', 'Done'])
+ expect(k.columns.map((c) => c.category)).toEqual(['unstarted', 'started', 'done'])
expect(new Set(k.columns.map((c) => c.id)).size).toBe(3)
expect(k.assignments).toEqual([])
})
@@ -53,6 +55,21 @@ describe('columns', () => {
expect(k.columns[1]).toMatchObject({ id: 'b', title: 'WIP', color: '#fff' })
expect(k.columns[0]).toEqual(board().columns[0])
})
+ it('setColumnCategory sets, changes and clears ONLY the target column', () => {
+ const set = setColumnCategory(board(), 'b', 'done')
+ expect(set.columns[1]).toEqual({ id: 'b', title: 'Doing', color: '#ffd60a', category: 'done' })
+ expect(set.columns[0]).toEqual(board().columns[0])
+ const cleared = setColumnCategory(set, 'b', undefined)
+ expect(cleared.columns[1]).toEqual(board().columns[1])
+ expect('category' in cleared.columns[1]).toBe(false)
+ })
+ it('setColumnCategory: unknown column or unchanged value returns the SAME board (no persist)', () => {
+ const k = board()
+ expect(setColumnCategory(k, 'nope', 'done')).toBe(k)
+ expect(setColumnCategory(k, 'a', undefined)).toBe(k)
+ const set = setColumnCategory(k, 'a', 'started')
+ expect(setColumnCategory(set, 'a', 'started')).toBe(set)
+ })
it('moveColumn before a target and to the end (null)', () => {
expect(moveColumn(board(), 'b', 'a').columns.map((c) => c.id)).toEqual(['b', 'a'])
expect(moveColumn(board(), 'a', null).columns.map((c) => c.id)).toEqual(['b', 'a'])
diff --git a/src/renderer/lib/kanban.ts b/src/renderer/lib/kanban.ts
index 46d4187c0..38b510898 100644
--- a/src/renderer/lib/kanban.ts
+++ b/src/renderer/lib/kanban.ts
@@ -1,6 +1,9 @@
-import type { CanvasNodeState, KanbanAssignment, KanbanColumn, Project, ProjectKanban } from '@shared/types'
+import type {
+ CanvasNodeState, KanbanAssignment, KanbanColumn, KanbanColumnCategory, Project, ProjectKanban
+} from '@shared/types'
+import { columnCategory } from '@shared/kanban-category'
import { SYSTEM_NODE_COLORS } from '../state/workspace'
-import { DEFAULT_BOARD_COLUMNS, makeColumnId } from '@shared/kanban-default-board'
+import { defaultBoardColumns } from '@shared/kanban-default-board'
import { autoLabelColor, boardLabels, cardMeta, createLabel, metaList, setCardLabels } from '@shared/kanban-labels'
// The card-meta + label transforms live in `@shared/kanban-labels` (the host core applies the
@@ -21,7 +24,7 @@ const kid = (prefix: string): string => `${prefix}-${Math.random().toString(36).
* shared definition so a board born on either surface is the same board. */
export function defaultKanban(): ProjectKanban {
return {
- columns: DEFAULT_BOARD_COLUMNS.map((c) => ({ id: makeColumnId(), title: c.title, color: c.color })),
+ columns: defaultBoardColumns(),
assignments: []
}
}
@@ -61,6 +64,26 @@ export function recolorColumn(k: ProjectKanban, columnId: string, color: string)
return { ...k, columns: k.columns.map((c) => (c.id === columnId ? { ...c, color } : c)) }
}
+/** Sets (or, with `undefined`, clears) a column's lifecycle category. Returns the SAME board when
+ * nothing changes (unknown column, or the value it already reads as), so a caller can skip a
+ * no-op persist. The UI confirms first when the column holds cards (`categoryChangeImpact`). */
+export function setColumnCategory(
+ k: ProjectKanban,
+ columnId: string,
+ category: KanbanColumnCategory | undefined
+): ProjectKanban {
+ const target = k.columns.find((c) => c.id === columnId)
+ if (!target || columnCategory(target) === columnCategory({ category })) return k
+ return {
+ ...k,
+ columns: k.columns.map((c) => {
+ if (c.id !== columnId) return c
+ const { category: _old, ...rest } = c
+ return category ? { ...rest, category } : rest
+ })
+ }
+}
+
/** Moves a column before `beforeId` (null = to the end). */
export function moveColumn(k: ProjectKanban, columnId: string, beforeId: string | null): ProjectKanban {
if (columnId === beforeId) return k
diff --git a/src/renderer/state/kanbanDisplay.test.ts b/src/renderer/state/kanbanDisplay.test.ts
new file mode 100644
index 000000000..edbf07543
--- /dev/null
+++ b/src/renderer/state/kanbanDisplay.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { parseKanbanDisplay, useKanbanDisplay } from './kanbanDisplay'
+
+describe('parseKanbanDisplay', () => {
+ it('reads a well-formed per-project map', () => {
+ expect(parseKanbanDisplay('{"p1":{"showClosed":true},"p2":{"showClosed":false}}')).toEqual({
+ p1: { showClosed: true },
+ p2: { showClosed: false }
+ })
+ })
+
+ it('is empty (every default) for missing or unparseable storage', () => {
+ expect(parseKanbanDisplay(null)).toEqual({})
+ expect(parseKanbanDisplay('{nope')).toEqual({})
+ expect(parseKanbanDisplay('[1,2]')).toEqual({})
+ expect(parseKanbanDisplay('"str"')).toEqual({})
+ })
+
+ it('keeps only literal booleans — a hand-edited value never flips a default', () => {
+ expect(parseKanbanDisplay('{"p1":{"showClosed":"yes"},"p2":7,"p3":{"showClosed":true,"x":1}}')).toEqual({
+ p1: {},
+ p3: { showClosed: true }
+ })
+ })
+})
+
+describe('useKanbanDisplay', () => {
+ it('closed columns are hidden until the user asks, per project', () => {
+ const s = useKanbanDisplay.getState()
+ expect(s.showClosed('p-a')).toBe(false)
+ s.setShowClosed('p-a', true)
+ expect(useKanbanDisplay.getState().showClosed('p-a')).toBe(true)
+ expect(useKanbanDisplay.getState().showClosed('p-b')).toBe(false)
+ })
+})
diff --git a/src/renderer/state/kanbanDisplay.ts b/src/renderer/state/kanbanDisplay.ts
new file mode 100644
index 000000000..31ea63c2e
--- /dev/null
+++ b/src/renderer/state/kanbanDisplay.ts
@@ -0,0 +1,68 @@
+import { create } from 'zustand'
+import { readLocal, writeLocal } from '../lib/localStore'
+
+// How ONE person looks at a project's board — PERSONAL, per machine: localStorage, never the
+// git-shared .nodeterm/project.json (same rule as the view mode and the card panel). What the board
+// SAYS (its columns, their categories) is shared; whether this user wants the `closed` columns in
+// front of them is not — one teammate hiding finished work must not hide it for everybody.
+//
+// Deliberately NOT here: the transient status chips (Running / Needs you / Unread). They filter on
+// second-by-second agent state, and a filter like that surviving a restart shows a board that is
+// wrong before anyone has looked at it. They live in KanbanView's component state.
+
+export const KANBAN_DISPLAY_KEY = 'nodeterm.kanbanDisplay'
+
+export interface ProjectBoardDisplay {
+ /** Show columns whose category is `closed`. Absent = hidden (the point of `closed`). */
+ showClosed?: boolean
+}
+
+export type KanbanDisplayMap = Record<string, ProjectBoardDisplay>
+
+const isRecord = (x: unknown): x is Record<string, unknown> =>
+ !!x && typeof x === 'object' && !Array.isArray(x)
+
+/** Parses the persisted map. Anything unreadable is "every default"; only literal booleans are
+ * kept, so a hand-edited value can never flip a default it did not spell exactly. */
+export function parseKanbanDisplay(raw: string | null): KanbanDisplayMap {
+ if (!raw) return {}
+ let parsed: unknown
+ try {
+ parsed = JSON.parse(raw)
+ } catch {
+ return {}
+ }
+ if (!isRecord(parsed)) return {}
+ const out: KanbanDisplayMap = {}
+ for (const [pid, v] of Object.entries(parsed)) {
+ if (!isRecord(v)) continue
+ const entry: ProjectBoardDisplay = {}
+ if (typeof v.showClosed === 'boolean') entry.showClosed = v.showClosed
+ out[pid] = entry
+ }
+ return out
+}
+
+function save(map: KanbanDisplayMap): void {
+ try {
+ writeLocal(KANBAN_DISPLAY_KEY, JSON.stringify(map))
+ } catch {
+ /* quota/private-mode: a display preference is a nicety, never fail the UI */
+ }
+}
+
+interface KanbanDisplayState {
+ byProject: KanbanDisplayMap
+ showClosed(projectId: string): boolean
+ setShowClosed(projectId: string, show: boolean): void
+}
+
+export const useKanbanDisplay = create<KanbanDisplayState>((set, get) => ({
+ byProject: parseKanbanDisplay(readLocal(KANBAN_DISPLAY_KEY)),
+ showClosed: (projectId) => get().byProject[projectId]?.showClosed === true,
+ setShowClosed: (projectId, show) => {
+ const byProject = { ...get().byProject, [projectId]: { ...get().byProject[projectId], showClosed: show } }
+ save(byProject)
+ set({ byProject })
+ }
+}))
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 4b28b9a63..746dc708f 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -10494,6 +10494,55 @@ button.group-node__setup:disabled {
.kanban-col__close:hover {
color: var(--danger);
}
+/* Lifecycle category marker (@shared/kanban-category): a quiet word beside the title, never a
+ second colour language — the column's own dot already carries its identity. */
+.kanban-col__category {
+ flex: 0 0 auto;
+ font-size: 9.5px;
+ font-weight: 700;
+ letter-spacing: 0.05em;
+ text-transform: uppercase;
+ color: rgba(var(--tint-rgb), 0.5);
+ border: 1px solid rgba(var(--tint-rgb), 0.14);
+ border-radius: 4px;
+ padding: 0 4px;
+ white-space: nowrap;
+}
+.kanban-col__menu {
+ background: none;
+ border: none;
+ color: rgba(var(--tint-rgb), 0.35);
+ cursor: pointer;
+ font-size: 13px;
+ line-height: 1;
+ padding: 0 2px;
+}
+.kanban-col__menu:hover {
+ color: var(--text-strong);
+}
+/* Board progress (cards in done+closed columns over every card) in the title strip. */
+.kanban-progress {
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+ margin-left: 6px;
+ font-size: 11px;
+ color: rgba(var(--tint-rgb), 0.55);
+ white-space: nowrap;
+ font-variant-numeric: tabular-nums;
+}
+.kanban-progress__bar {
+ width: 56px;
+ height: 4px;
+ border-radius: 2px;
+ background: rgba(var(--tint-rgb), 0.1);
+ overflow: hidden;
+}
+.kanban-progress__fill {
+ display: block;
+ height: 100%;
+ background: var(--state-success);
+}
.kanban-col__swatches {
display: flex;
gap: 6px;
diff --git a/src/shared/kanban-category.test.ts b/src/shared/kanban-category.test.ts
new file mode 100644
index 000000000..43d5cde7a
--- /dev/null
+++ b/src/shared/kanban-category.test.ts
@@ -0,0 +1,147 @@
+import { describe, expect, it } from 'vitest'
+import type { KanbanColumn, ProjectKanban } from './types'
+import {
+ CATEGORY_LABELS,
+ KANBAN_COLUMN_CATEGORIES,
+ boardProgress,
+ categoryChangeImpact,
+ categoryChangeMessage,
+ columnCategory,
+ defaultCompletionColumnId,
+ isCompletedCategory
+} from './kanban-category'
+
+const col = (id: string, category?: unknown): KanbanColumn =>
+ ({ id, title: id, color: '#fff', ...(category !== undefined ? { category } : {}) }) as KanbanColumn
+
+const board = (): ProjectKanban => ({
+ columns: [col('todo', 'unstarted'), col('doing', 'started'), col('done', 'done'), col('gone', 'closed')],
+ assignments: [
+ { nodeId: 'a', columnId: 'todo' },
+ { nodeId: 'b', columnId: 'doing' },
+ { nodeId: 'c', columnId: 'done' },
+ { nodeId: 'd', columnId: 'gone' },
+ { nodeId: 'dead', columnId: 'done' }
+ ]
+})
+
+describe('columnCategory', () => {
+ it('reads the four known values', () => {
+ for (const c of KANBAN_COLUMN_CATEGORIES) expect(columnCategory(col('x', c))).toBe(c)
+ })
+
+ it('reads an absent, unknown or non-string value as ABSENT (never throws)', () => {
+ expect(columnCategory(col('x'))).toBeUndefined()
+ expect(columnCategory(col('x', 'blocked'))).toBeUndefined()
+ expect(columnCategory(col('x', 'constructor'))).toBeUndefined()
+ expect(columnCategory(col('x', 3))).toBeUndefined()
+ expect(columnCategory(col('x', { evil: true }))).toBeUndefined()
+ expect(columnCategory(undefined)).toBeUndefined()
+ })
+
+ it('labels every category', () => {
+ expect(Object.keys(CATEGORY_LABELS).sort()).toEqual([...KANBAN_COLUMN_CATEGORIES].sort())
+ })
+
+ it('done and closed are the completed categories', () => {
+ expect(KANBAN_COLUMN_CATEGORIES.filter(isCompletedCategory)).toEqual(['done', 'closed'])
+ expect(isCompletedCategory(undefined)).toBe(false)
+ })
+})
+
+describe('boardProgress', () => {
+ it('counts live cards in done+closed columns over every live card, Ungrouped included', () => {
+ // e is unassigned (Ungrouped) — unfinished work; `dead` is not a live card.
+ expect(boardProgress(board(), ['a', 'b', 'c', 'd', 'e'])).toEqual({ complete: 2, total: 5 })
+ })
+
+ it('is null when no column says what "complete" means', () => {
+ const k: ProjectKanban = {
+ columns: [col('x'), col('y', 'started')],
+ assignments: [{ nodeId: 'a', columnId: 'x' }]
+ }
+ expect(boardProgress(k, ['a'])).toBeNull()
+ })
+
+ it('is null for an empty board (0/0 is not progress)', () => {
+ expect(boardProgress(board(), [])).toBeNull()
+ })
+
+ it('a dangling assignment is Ungrouped, not complete', () => {
+ const k: ProjectKanban = { ...board(), assignments: [{ nodeId: 'a', columnId: 'deleted' }] }
+ expect(boardProgress(k, ['a'])).toEqual({ complete: 0, total: 1 })
+ })
+})
+
+describe('defaultCompletionColumnId', () => {
+ it('prefers the first done column', () => {
+ expect(defaultCompletionColumnId([col('a', 'done'), col('b', 'closed'), col('c', 'done')])).toBe('a')
+ })
+
+ it('falls back to the first closed column', () => {
+ expect(defaultCompletionColumnId([col('a', 'started'), col('b', 'closed')])).toBe('b')
+ })
+
+ it('falls back to the last column when nothing is categorized (the old default)', () => {
+ expect(defaultCompletionColumnId([col('a'), col('b')])).toBe('b')
+ })
+
+ it('is undefined with no columns', () => {
+ expect(defaultCompletionColumnId([])).toBeUndefined()
+ })
+})
+
+describe('categoryChangeImpact', () => {
+ it('names the live cards a change would re-mean', () => {
+ expect(categoryChangeImpact(board(), 'doing', 'done', ['a', 'b', 'c', 'd'])).toEqual({
+ cards: 1,
+ from: 'started',
+ to: 'done'
+ })
+ })
+
+ it('is null for an empty column — nothing to re-mean', () => {
+ expect(categoryChangeImpact(board(), 'doing', 'done', ['a', 'c'])).toBeNull()
+ })
+
+ it('is null when the category does not actually change', () => {
+ expect(categoryChangeImpact(board(), 'doing', 'started', ['b'])).toBeNull()
+ })
+
+ it('treats an unknown stored value as absent, so clearing it is not a change', () => {
+ const k: ProjectKanban = { columns: [col('x', 'blocked')], assignments: [{ nodeId: 'a', columnId: 'x' }] }
+ expect(categoryChangeImpact(k, 'x', undefined, ['a'])).toBeNull()
+ expect(categoryChangeImpact(k, 'x', 'done', ['a'])).toEqual({ cards: 1, from: undefined, to: 'done' })
+ })
+
+ it('is null for an unknown column', () => {
+ expect(categoryChangeImpact(board(), 'nope', 'done', ['a'])).toBeNull()
+ })
+})
+
+describe('categoryChangeMessage', () => {
+ it('says the cards will count as finished when a column becomes done', () => {
+ const m = categoryChangeMessage('Review', { cards: 1, from: 'started', to: 'done' }, false)
+ expect(m).toContain('"Review"')
+ expect(m).toContain('Started')
+ expect(m).toContain('Done')
+ expect(m).toContain('1 card will count as finished')
+ })
+
+ it('says they will no longer count when a done column stops being one', () => {
+ expect(categoryChangeMessage('Done', { cards: 3, from: 'done', to: undefined }, false)).toContain(
+ '3 cards will no longer count as finished'
+ )
+ })
+
+ it('warns that the cards disappear from view when a column becomes closed and closed is hidden', () => {
+ const hidden = categoryChangeMessage('Old', { cards: 2, from: undefined, to: 'closed' }, true)
+ expect(hidden).toContain('hidden')
+ const shown = categoryChangeMessage('Old', { cards: 2, from: undefined, to: 'closed' }, false)
+ expect(shown).not.toContain('hidden')
+ })
+
+ it('still names the count for a change between two unfinished categories', () => {
+ expect(categoryChangeMessage('Q', { cards: 4, from: 'unstarted', to: 'started' }, false)).toContain('4 cards')
+ })
+})
diff --git a/src/shared/kanban-category.ts b/src/shared/kanban-category.ts
new file mode 100644
index 000000000..33e61fc90
--- /dev/null
+++ b/src/shared/kanban-category.ts
@@ -0,0 +1,143 @@
+/**
+ * Column lifecycle categories — what a column MEANS, independent of what it is called.
+ *
+ * A board's columns are free-form ("Backlog", "Review", "Shipped"), so nothing could tell which of
+ * them hold finished work. The optional `KanbanColumn.category` says it once, per column, and three
+ * things read it: the board's progress (`boardProgress`), hiding `closed` columns behind a toggle,
+ * and the default GitHub completion column (`defaultCompletionColumnId`).
+ *
+ * It lives in `shared` because the board is git-shared content read by the renderer, the core (the
+ * relay's board verbs seed the default board) and — across the repo boundary — the phone, which
+ * must at least tolerate the field.
+ *
+ * **Every reader goes through `columnCategory`.** The value comes from a hand-editable, git-shared
+ * file, so a stored string outside the closed set (a typo, or a category a NEWER build added) reads
+ * as ABSENT rather than being trusted, and a non-string never reaches a comparison. The value
+ * itself is left in the file: dropping an unknown string on save would erase a newer build's data
+ * from the shared file the moment an older teammate saved.
+ */
+import type { KanbanColumn, KanbanColumnCategory, ProjectKanban } from './types'
+
+/** The closed set, in lifecycle order (the order the column menu lists them). */
+export const KANBAN_COLUMN_CATEGORIES: readonly KanbanColumnCategory[] = [
+ 'unstarted',
+ 'started',
+ 'done',
+ 'closed'
+]
+
+/** Menu / chip wording for each category. */
+export const CATEGORY_LABELS: Readonly<Record<KanbanColumnCategory, string>> = {
+ unstarted: 'Not started',
+ started: 'Started',
+ done: 'Done',
+ closed: 'Closed'
+}
+
+const KNOWN = new Set<string>(KANBAN_COLUMN_CATEGORIES)
+
+/** The column's category, or undefined when absent, unknown or not a string. Never throws. */
+export function columnCategory(
+ col: Pick<KanbanColumn, 'category'> | { category?: unknown } | undefined | null
+): KanbanColumnCategory | undefined {
+ const c = (col as { category?: unknown } | undefined | null)?.category
+ return typeof c === 'string' && KNOWN.has(c) ? (c as KanbanColumnCategory) : undefined
+}
+
+/** `done` and `closed` both mean "no work left here" — the numerator of the board's progress. */
+export function isCompletedCategory(c: KanbanColumnCategory | undefined): boolean {
+ return c === 'done' || c === 'closed'
+}
+
+/**
+ * The board's progress: live cards sitting in a `done`/`closed` column over EVERY live card
+ * (Ungrouped included — an unfiled card is unfinished work, not work that does not exist).
+ *
+ * Null when it would be meaningless: no column carries a completed category (the board has not
+ * said what "complete" means, so any number would be invented), or there are no cards (0/0).
+ * A dangling assignment (its column deleted elsewhere) is Ungrouped, as everywhere on the board.
+ */
+export function boardProgress(
+ k: ProjectKanban,
+ liveIds: readonly string[]
+): { complete: number; total: number } | null {
+ const completedCols = new Set(
+ k.columns.filter((c) => isCompletedCategory(columnCategory(c))).map((c) => c.id)
+ )
+ if (completedCols.size === 0 || liveIds.length === 0) return null
+ const live = new Set(liveIds)
+ const complete = new Set(
+ k.assignments
+ .filter((a) => live.has(a?.nodeId) && completedCols.has(a.columnId))
+ .map((a) => a.nodeId)
+ ).size
+ return { complete, total: live.size }
+}
+
+/**
+ * The column a GitHub issue should close into by default: the first `done` column, else the first
+ * `closed` one, else the LAST column — which is what the default was before categories existed, so
+ * an uncategorized board keeps exactly its old behaviour.
+ */
+export function defaultCompletionColumnId(
+ columns: ReadonlyArray<Pick<KanbanColumn, 'id' | 'category'>>
+): string | undefined {
+ return (
+ columns.find((c) => columnCategory(c) === 'done')?.id ??
+ columns.find((c) => columnCategory(c) === 'closed')?.id ??
+ columns.at(-1)?.id
+ )
+}
+
+/**
+ * What changing a column's category would do to the cards already in it — or null when it would
+ * do nothing (unknown column, no live cards in it, or no actual change).
+ *
+ * A category is not a label on the column, it is a claim about every card in it: moving "Review"
+ * from `started` to `done` silently counts its cards as finished, and moving a column to `closed`
+ * can hide its cards behind the "show closed" toggle. So the board refuses to do either SILENTLY:
+ * a non-null answer means the UI must confirm, naming the count. An empty column changes freely.
+ */
+export function categoryChangeImpact(
+ k: ProjectKanban,
+ columnId: string,
+ next: KanbanColumnCategory | undefined,
+ liveIds: readonly string[]
+): { cards: number; from: KanbanColumnCategory | undefined; to: KanbanColumnCategory | undefined } | null {
+ const column = k.columns.find((c) => c.id === columnId)
+ if (!column) return null
+ const from = columnCategory(column)
+ const to = columnCategory({ category: next })
+ if (from === to) return null
+ const live = new Set(liveIds)
+ const cards = new Set(
+ k.assignments.filter((a) => a?.columnId === columnId && live.has(a.nodeId)).map((a) => a.nodeId)
+ ).size
+ return cards > 0 ? { cards, from, to } : null
+}
+
+/**
+ * The confirmation sentence for a category change that would re-mean cards (`categoryChangeImpact`
+ * answered non-null). It names the column, the before/after and the COUNT, then the consequence
+ * the user cannot see from the menu: the progress numerator moving, or the cards leaving view
+ * when the column becomes `closed` while this user hides closed columns.
+ */
+export function categoryChangeMessage(
+ title: string,
+ impact: { cards: number; from: KanbanColumnCategory | undefined; to: KanbanColumnCategory | undefined },
+ closedHidden: boolean
+): string {
+ const name = (c: KanbanColumnCategory | undefined): string => (c ? CATEGORY_LABELS[c] : 'No category')
+ const n = `${impact.cards} card${impact.cards === 1 ? '' : 's'}`
+ const head = `Change "${title}" from ${name(impact.from)} to ${name(impact.to)}?`
+ const wasDone = isCompletedCategory(impact.from)
+ const nowDone = isCompletedCategory(impact.to)
+ const effects: string[] = []
+ if (nowDone && !wasDone) effects.push(`Its ${n} will count as finished in the board's progress.`)
+ else if (wasDone && !nowDone) effects.push(`Its ${n} will no longer count as finished.`)
+ else effects.push(`This changes what the column means for its ${n}.`)
+ if (impact.to === 'closed' && closedHidden) {
+ effects.push('Closed columns are hidden on your board, so the column and its cards will leave view.')
+ }
+ return [head, ...effects].join(' ')
+}
diff --git a/src/shared/kanban-default-board.test.ts b/src/shared/kanban-default-board.test.ts
index f95f9d453..c95680897 100644
--- a/src/shared/kanban-default-board.test.ts
+++ b/src/shared/kanban-default-board.test.ts
@@ -20,6 +20,13 @@ describe('DEFAULT_BOARD_COLUMNS', () => {
])
expect(DEFAULT_BOARD_COLUMNS.map((c) => c.color)).toEqual(['#0a84ff', '#ffd60a', '#32d74b'])
})
+
+ // The lifecycle category is ADDITIVE to the cross-surface contract: the phone's copy may lack it
+ // (a board it seeds simply has uncategorized columns, which every reader tolerates), but a board
+ // born on the desktop or through the relay knows which column holds finished work.
+ it('maps them onto the lifecycle: unstarted / started / done', () => {
+ expect(DEFAULT_BOARD_COLUMNS.map((c) => c.category)).toEqual(['unstarted', 'started', 'done'])
+ })
})
describe('makeColumnId', () => {
diff --git a/src/shared/kanban-default-board.ts b/src/shared/kanban-default-board.ts
index 01810920e..3eb30f8cd 100644
--- a/src/shared/kanban-default-board.ts
+++ b/src/shared/kanban-default-board.ts
@@ -8,25 +8,40 @@
* and, across the repo boundary, nodeterm-ios `KanbanDefaults` (which cannot import this file and
* therefore copies it verbatim under a pinning test).
*
- * Only the TITLES, their ORDER and their COLORS are shared. Column ids are minted per board and are
+ * Only the TITLES, their ORDER, their COLORS and their lifecycle CATEGORY are shared (the category
+ * is additive: a surface whose copy lacks it seeds uncategorized columns, which every reader
+ * tolerates — see @shared/kanban-category). Column ids are minted per board and are
* deliberately random: a board is created exactly once, by whichever surface got there first, and
* every later reader addresses columns by the ids that board carries — so two surfaces agreeing on
* an id would buy nothing and a fixed id would collide across projects.
*/
import { SYSTEM_NODE_COLORS } from './node-colors'
+import type { KanbanColumn, KanbanColumnCategory } from './types'
export interface DefaultBoardColumn {
title: string
color: string
+ category: KanbanColumnCategory
}
/** The three starting columns, in board order. */
export const DEFAULT_BOARD_COLUMNS: readonly DefaultBoardColumn[] = [
- { title: 'To Do', color: SYSTEM_NODE_COLORS[0] },
- { title: 'In Progress', color: SYSTEM_NODE_COLORS[2] },
- { title: 'Done', color: SYSTEM_NODE_COLORS[1] }
+ { title: 'To Do', color: SYSTEM_NODE_COLORS[0], category: 'unstarted' },
+ { title: 'In Progress', color: SYSTEM_NODE_COLORS[2], category: 'started' },
+ { title: 'Done', color: SYSTEM_NODE_COLORS[1], category: 'done' }
] as const
+/** The default columns with freshly minted ids — the ONE place a seeded column's shape is spelled,
+ * so the renderer's lazy default and the core's relay seeding cannot drift apart. */
+export function defaultBoardColumns(mintId: () => string = makeColumnId): KanbanColumn[] {
+ return DEFAULT_BOARD_COLUMNS.map((c) => ({
+ id: mintId(),
+ title: c.title,
+ color: c.color,
+ category: c.category
+ }))
+}
+
/**
* A column id in the desktop's shape: `kcol-<8 chars of base36>`.
*
diff --git a/src/shared/types.ts b/src/shared/types.ts
index fcd8467f4..4c69f9bb0 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -616,11 +616,19 @@ export interface BridgeLink {
target: string
}
+/** Where a column sits in a card's lifecycle (see @shared/kanban-category). A closed set; an
+ * unknown value read from a hand-edited or newer file reads as ABSENT (`columnCategory`), and is
+ * left in the file untouched so a newer build's value survives an older build's save. */
+export type KanbanColumnCategory = 'unstarted' | 'started' | 'done' | 'closed'
+
/** One kanban board column. Column order = array order in ProjectKanban.columns. */
export interface KanbanColumn {
id: string
title: string
color: string
+ /** Optional lifecycle category. Absent = uncategorized (the pre-category board, and any column
+ * the user never categorized). Read it through `columnCategory`, never directly. */
+ category?: KanbanColumnCategory
}
/** Assignment of one session node to a board column. A session with no assignment sits