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.

7.2 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import { ensureProjectBoard, setProjectCardColumn } from './project-kanban-write'
import { DEFAULT_BOARD_COLUMNS } from '../shared/kanban-default-board'
import { isValidRank } from '../shared/kanban-rank'

const NOW = new Date('2026-09-10T12:00:00.000Z')

function file(extra: Record<string, unknown> = {}): string {
  return JSON.stringify({
    version: 1,
    rev: 7,
    savedAt: '2026-01-01T00:00:00.000Z',
    name: 'p',
    color: '#0a84ff',
    nodes: [{ id: 'term-a-1', kind: 'terminal' }],
    ...extra
  })
}

const parse = (s: string | null): Record<string, any> => JSON.parse(s ?? 'null')

describe('ensureProjectBoard', () => {
  it('seeds the shared default columns, in order, on a project with no board', () => {
    const out = parse(ensureProjectBoard(file(), NOW, () => 'kcol-fixed'))
    expect(out.kanban.columns.map((c: { title: string }) => c.title)).toEqual(
      DEFAULT_BOARD_COLUMNS.map((c) => c.title)
    )
    expect(out.kanban.columns.map((c: { color: string }) => c.color)).toEqual(
      DEFAULT_BOARD_COLUMNS.map((c) => c.color)
    )
    expect(out.kanban.assignments).toEqual([])
    expect(out.rev).toBe(8)
    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)
    expect(new Set(ids).size).toBe(3)
    for (const id of ids) expect(id).toMatch(/^kcol-[a-z0-9]{1,8}$/)
  })

  it('is idempotent: a board that already has a column is not touched', () => {
    const raw = file({ kanban: { columns: [{ id: 'kcol-x', title: 'Mine', color: '#fff' }], assignments: [] } })
    expect(ensureProjectBoard(raw, NOW)).toBeNull()
  })

  it('seeds over an EMPTY columns array (a board block with nothing in it is no board)', () => {
    const out = parse(ensureProjectBoard(file({ kanban: { columns: [], assignments: [] } }), NOW))
    expect(out.kanban.columns).toHaveLength(3)
  })

  it('keeps board metadata the phone has no UI for', () => {
    const raw = file({ kanban: { columns: [], meta: [{ nodeId: 'term-a-1', priority: 'high' }], labels: [{ id: 'l1' }] } })
    const out = parse(ensureProjectBoard(raw, NOW))
    expect(out.kanban.meta).toEqual([{ nodeId: 'term-a-1', priority: 'high' }])
    expect(out.kanban.labels).toEqual([{ id: 'l1' }])
  })

  it('round-trips every field this version does not know', () => {
    const out = parse(ensureProjectBoard(file({ bridges: [{ id: 'b' }], somethingFuture: 42 }), NOW))
    expect(out.bridges).toEqual([{ id: 'b' }])
    expect(out.somethingFuture).toBe(42)
  })

  it('refuses a file it could not parse, or one of another shape', () => {
    expect(ensureProjectBoard('{not json', NOW)).toBeNull()
    expect(ensureProjectBoard('[]', NOW)).toBeNull()
    expect(ensureProjectBoard(JSON.stringify({ version: 2, rev: 1, nodes: [] }), NOW)).toBeNull()
    expect(ensureProjectBoard(JSON.stringify({ version: 1, nodes: [] }), NOW)).toBeNull()
  })

  it('refuses a `kanban` that is not an object rather than replacing it', () => {
    expect(ensureProjectBoard(file({ kanban: 'nope' }), NOW)).toBeNull()
    expect(ensureProjectBoard(file({ kanban: [] }), NOW)).toBeNull()
  })
})

describe('setProjectCardColumn', () => {
  const board = (assignments: unknown[] = []): string =>
    file({
      kanban: {
        columns: [
          { id: 'kcol-a', title: 'To Do', color: '#0a84ff' },
          { id: 'kcol-b', title: 'Done', color: '#32d74b' }
        ],
        assignments,
        meta: [{ nodeId: 'term-a-1', priority: 'high' }]
      }
    })

  it('assigns an unassigned card and bumps rev', () => {
    const out = parse(setProjectCardColumn(board(), 'term-a-1', 'kcol-a', NOW))
    expect(out.kanban.assignments).toEqual([{ nodeId: 'term-a-1', columnId: 'kcol-a', rank: expect.any(String) }])
    expect(isValidRank(out.kanban.assignments[0].rank)).toBe(true)
    expect(out.rev).toBe(8)
  })

  it('re-points an existing assignment instead of adding a second one', () => {
    const out = parse(
      setProjectCardColumn(board([{ nodeId: 'term-a-1', columnId: 'kcol-a' }]), 'term-a-1', 'kcol-b', NOW)
    )
    expect(out.kanban.assignments).toEqual([{ nodeId: 'term-a-1', columnId: 'kcol-b', rank: expect.any(String) }])
  })

  it('columnId null drops the assignment (the virtual Ungrouped column)', () => {
    const out = parse(
      setProjectCardColumn(board([{ nodeId: 'term-a-1', columnId: 'kcol-a' }]), 'term-a-1', null, NOW)
    )
    expect(out.kanban.assignments).toEqual([])
  })

  it('leaves other cards, and the card metadata, alone', () => {
    const out = parse(
      setProjectCardColumn(board([{ nodeId: 'term-z-9', columnId: 'kcol-b' }]), 'term-a-1', 'kcol-a', NOW)
    )
    expect(out.kanban.assignments).toEqual([
      { nodeId: 'term-z-9', columnId: 'kcol-b' },
      { nodeId: 'term-a-1', columnId: 'kcol-a', rank: expect.any(String) }
    ])
    expect(out.kanban.meta).toEqual([{ nodeId: 'term-a-1', priority: 'high' }])
  })

  // The phone's move names no anchor, so it follows the desktop's unanchored rule: the TOP of the
  // destination, where the person who just filed it will look for it.
  it('an unanchored move lands at the TOP of a column that already has cards', () => {
    const out = parse(
      setProjectCardColumn(
        board([
          { nodeId: 'term-z-9', columnId: 'kcol-b' },
          { nodeId: 'term-y-8', columnId: 'kcol-b' },
          { nodeId: 'term-a-1', columnId: 'kcol-a' }
        ]),
        'term-a-1',
        'kcol-b',
        NOW
      )
    )
    expect(out.kanban.assignments.map((a: { nodeId: string }) => a.nodeId)).toEqual([
      'term-a-1',
      'term-z-9',
      'term-y-8'
    ])
  })

  it('refuses a column this board does not have', () => {
    expect(setProjectCardColumn(board(), 'term-a-1', 'kcol-gone', NOW)).toBeNull()
  })

  it('refuses a no-op move (a retry must not churn rev)', () => {
    expect(
      setProjectCardColumn(board([{ nodeId: 'term-a-1', columnId: 'kcol-a' }]), 'term-a-1', 'kcol-a', NOW)
    ).toBeNull()
    expect(setProjectCardColumn(board(), 'term-a-1', null, NOW)).toBeNull()
  })

  it('accepts a node id the canvas does not list yet (it may have just been registered)', () => {
    const out = parse(setProjectCardColumn(board(), 'term-new-1', 'kcol-a', NOW))
    expect(out.kanban.assignments).toEqual([{ nodeId: 'term-new-1', columnId: 'kcol-a', rank: expect.any(String) }])
  })

  it('refuses a project with no board at all — the caller seeds one first', () => {
    expect(setProjectCardColumn(file(), 'term-a-1', 'kcol-a', NOW)).toBeNull()
    expect(setProjectCardColumn(file(), 'term-a-1', null, NOW)).toBeNull()
  })

  it('refuses an empty node id and an unparsable file', () => {
    expect(setProjectCardColumn(board(), '', 'kcol-a', NOW)).toBeNull()
    expect(setProjectCardColumn('{not json', 'term-a-1', 'kcol-a', NOW)).toBeNull()
  })
})