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.

14.8 KB
Raw Blame
import { describe, it, expect } from 'vitest'
import { applyCanvasOp, contentOf, diffContent, type CanvasContent } from './canvas-content'
import { MUTATION_MAX_BYTES } from './canvas-mutations'
import { defaultKanbanFor } from './kanban-default-board'
import type { CanvasMutation, CanvasNodeState, ProjectKanban } from './types'

const node = (id: string, x = 0) => ({ id, kind: 'terminal', position: { x, y: 0 } }) as any
const empty: CanvasContent = { nodes: [], bridges: [], ropes: [] }

describe('applyCanvasOp', () => {
  it('routes each family to its applier', () => {
    let c = applyCanvasOp(empty, { op: 'upsert', node: node('n1') }, 'p')
    c = applyCanvasOp(c, { op: 'edge-upsert', kind: 'bridge', edge: { id: 'b', source: 'n1', target: 'n1' } }, 'p')
    c = applyCanvasOp(c, { op: 'kb-card', assignment: { nodeId: 'n1', columnId: 'c' } }, 'p')
    expect(c.nodes.map((n) => n.id)).toEqual(['n1'])
    expect(c.bridges.map((b) => b.id)).toEqual(['b'])
    expect(c.kanban?.assignments).toEqual([{ nodeId: 'n1', columnId: 'c' }])
  })
  it('strips exec fields from an inbound node (a peer may not set our shell)', () => {
    const c = applyCanvasOp(empty, { op: 'upsert', node: { ...node('n1'), shell: '/bin/evil' } }, 'p')
    expect((c.nodes[0] as { shell?: string }).shell).toBeUndefined()
  })
  it('refuses an edge op with a bad endpoint id', () => {
    const c = applyCanvasOp(empty, { op: 'edge-upsert', kind: 'rope', edge: { id: 'r', source: '', target: 'x' } } as any, 'p')
    expect(c.ropes).toEqual([])
  })
  it('an unchanged content is the same object (no spurious flush)', () => {
    const c = applyCanvasOp(empty, { op: 'remove', id: 'ghost' }, 'p')
    expect(c).toBe(empty)
  })
})

/**
 * "Nothing changed" is the SAME object, for every family — the authority skips a flush on it and
 * the projects store skips a setState (and the save it would schedule). A duplicate op is the
 * common case, not a corner: every Server Edition tab re-casts what it received, the authority's
 * own published diff echoes back to it, and a reconnect replays.
 */
describe('applyCanvasOp — identity when nothing changed', () => {
  const held: CanvasContent = {
    nodes: [
      { id: 'a', kind: 'terminal', position: { x: 1, y: 2 }, size: { width: 10, height: 20 }, title: 'A', tags: ['x'] } as CanvasNodeState,
      node('b')
    ],
    bridges: [{ id: 'e1', source: 'a', target: 'b' }],
    ropes: []
  }

  it('a duplicate node upsert (a fresh object of the same value) is a no-op', () => {
    const copy = JSON.parse(JSON.stringify(held.nodes[0])) as CanvasNodeState
    expect(applyCanvasOp(held, { op: 'upsert', node: copy }, 'p')).toBe(held)
  })

  it('a key order difference is still the same value', () => {
    const n = held.nodes[0]
    const reordered = { tags: n.tags, title: n.title, size: { height: 20, width: 10 }, position: { y: 2, x: 1 }, kind: n.kind, id: n.id } as CanvasNodeState
    expect(applyCanvasOp(held, { op: 'upsert', node: reordered }, 'p')).toBe(held)
  })

  it('an upsert that changes one field is a change, and only that node is replaced', () => {
    const out = applyCanvasOp(held, { op: 'upsert', node: { ...held.nodes[0], tags: ['y'] } }, 'p')
    expect(out).not.toBe(held)
    expect(out.nodes[0].tags).toEqual(['y'])
    expect(out.nodes[1]).toBe(held.nodes[1])
    expect(out.bridges).toBe(held.bridges)
  })

  it('a peer upsert without OUR exec field is a no-op when nothing else differs (we keep our shell)', () => {
    const mine: CanvasContent = { ...held, nodes: [{ ...node('s'), shell: '/bin/zsh' }] }
    const out = applyCanvasOp(mine, { op: 'upsert', node: node('s') }, 'p')
    expect(out).toBe(mine)
    const moved = applyCanvasOp(mine, { op: 'upsert', node: node('s', 50) }, 'p')
    expect(moved.nodes[0]).toMatchObject({ shell: '/bin/zsh', position: { x: 50, y: 0 } })
  })

  // `carryLocalNodeExec` re-attaches our `ssh.extraArgs` together with `execTrusted: undefined`
  // when we never had one — a key JSON drops. Counting it as a difference would make every peer
  // drag of an ssh terminal with jump-host args a "change" even when nothing moved.
  it('a duplicate upsert of our ssh node (extraArgs carried back) is a no-op', () => {
    const ssh = { host: 'h', user: 'u', extraArgs: '-J jump' }
    const mine: CanvasContent = { ...held, nodes: [{ ...node('s'), ssh }] }
    expect(applyCanvasOp(mine, { op: 'upsert', node: { ...node('s'), ssh: { host: 'h', user: 'u' } } }, 'p')).toBe(mine)
  })

  it('a duplicate edge upsert, and a remove of an edge we lack, are no-ops', () => {
    expect(applyCanvasOp(held, { op: 'edge-upsert', kind: 'bridge', edge: { id: 'e1', source: 'a', target: 'b' } }, 'p')).toBe(held)
    expect(applyCanvasOp(held, { op: 'edge-remove', kind: 'rope', id: 'nope' }, 'p')).toBe(held)
  })

  it('a board op that changes nothing on a held board is a no-op', () => {
    const board: ProjectKanban = { columns: [{ id: 'k1', title: 'T', color: '#000' }], assignments: [{ nodeId: 'a', columnId: 'k1' }] }
    const c: CanvasContent = { ...held, kanban: board }
    expect(applyCanvasOp(c, { op: 'kb-card', assignment: { nodeId: 'a', columnId: 'k1' } }, 'p')).toBe(c)
    expect(applyCanvasOp(c, { op: 'kb-card-remove', nodeId: 'zz' }, 'p')).toBe(c)
    expect(applyCanvasOp(c, { op: 'kb-column', column: { id: 'k1', title: 'T', color: '#000' } }, 'p')).toBe(c)
    // No `meta` / `labels` / `views` list at all reads exactly like an empty one — writing `[]`
    // into the file for a remove of something that was never there is not a change.
    expect(applyCanvasOp(c, { op: 'kb-meta-remove', nodeId: 'a' }, 'p')).toBe(c)
    expect(applyCanvasOp(c, { op: 'kb-label-remove', id: 'l1' }, 'p')).toBe(c)
    expect(applyCanvasOp(c, { op: 'kb-view-remove', id: 'v1' }, 'p')).toBe(c)
  })

  it('a board op that leaves the LAZY default as it was keeps the board absent', () => {
    const def = defaultKanbanFor('p')
    const out1 = applyCanvasOp(held, { op: 'kb-card-remove', nodeId: 'a' }, 'p')
    expect(out1).toBe(held)
    const out2 = applyCanvasOp(held, { op: 'kb-column-order', ids: def.columns.map((c) => c.id) }, 'p')
    expect(out2).toBe(held)
    expect(applyCanvasOp(held, { op: 'kb-column', column: def.columns[0] }, 'p')).toBe(held)
  })

  it('a board op that DOES change the lazy default materializes the board', () => {
    const out = applyCanvasOp(held, { op: 'kb-card', assignment: { nodeId: 'a', columnId: defaultKanbanFor('p').columns[0].id } }, 'p')
    expect(out).not.toBe(held)
    expect(out.kanban?.columns).toEqual(defaultKanbanFor('p').columns)
    expect(out.nodes).toBe(held.nodes)
  })
})

describe('applyCanvasOp — refusals', () => {
  const c: CanvasContent = { nodes: [node('a')], bridges: [], ropes: [] }
  const refused: unknown[] = [
    null,
    { op: 'nope' },
    { op: 'upsert', node: { id: '', position: { x: 0, y: 0 } } },
    { op: 'upsert', node: { id: 'b', position: { x: Number.NaN, y: 0 } } },
    { op: 'remove', id: '' },
    { op: 'edge-upsert', kind: 'bridges', edge: { id: 'x', source: 'a', target: 'a' } },
    { op: 'edge-remove', kind: 'rope', id: 'r'.repeat(200) },
    { op: 'kb-card', assignment: { nodeId: '', columnId: 'k' } },
    { op: 'kb-nope' }
  ]
  for (const m of refused) {
    it(`leaves the content untouched for ${JSON.stringify(m)?.slice(0, 60)}`, () => {
      expect(applyCanvasOp(c, m as CanvasMutation, 'p')).toBe(c)
    })
  }

  it('a board op is applied in its sanitized form (an off-palette label colour is repaired)', () => {
    const out = applyCanvasOp(c, { op: 'kb-label', label: { id: 'l1', name: 'Bug', color: 'hotpink' as never } }, 'p')
    expect(out.kanban?.labels).toEqual([{ id: 'l1', name: 'Bug', color: 'default' }])
  })

  // The byte cap is the TRANSPORT's (the reflector refuses, the publisher never casts): an op that
  // reached a reducer has already passed it or never travelled at all. The projects store also
  // takes this client's OWN writes to a background project through here (cold open, a canvas-control
  // sticky write), and silently dropping one of those would lose the user's edit.
  it('does not re-apply the wire byte cap', () => {
    const big = { ...node('big'), kind: 'sticky', text: 'x'.repeat(MUTATION_MAX_BYTES) }
    const out = applyCanvasOp(c, { op: 'upsert', node: big }, 'p')
    expect(out.nodes.map((n) => n.id)).toEqual(['a', 'big'])
  })

  it('a node remove leaves its card on the board (placements are pruned lazily, spec §2)', () => {
    const board: ProjectKanban = { columns: [{ id: 'k1', title: 'T', color: '#000' }], assignments: [{ nodeId: 'a', columnId: 'k1' }] }
    const out = applyCanvasOp({ ...c, kanban: board }, { op: 'remove', id: 'a' }, 'p')
    expect(out.nodes).toEqual([])
    expect(out.kanban).toBe(board)
  })

  it('never mutates its input', () => {
    const frozen: CanvasContent = Object.freeze({
      nodes: Object.freeze([Object.freeze(node('a'))]) as CanvasNodeState[],
      bridges: Object.freeze([]) as never,
      ropes: Object.freeze([]) as never
    })
    expect(() => {
      applyCanvasOp(frozen, { op: 'upsert', node: node('a', 9) }, 'p')
      applyCanvasOp(frozen, { op: 'edge-upsert', kind: 'rope', edge: { id: 'r', source: 'a', target: 'a' } }, 'p')
      applyCanvasOp(frozen, { op: 'kb-card', assignment: { nodeId: 'a', columnId: 'k' } }, 'p')
    }).not.toThrow()
  })
})

describe('contentOf', () => {
  it('reads absent edge lists as empty and carries the board only when present', () => {
    const nodes = [node('a')]
    expect(contentOf({ nodes })).toEqual({ nodes, bridges: [], ropes: [] })
    expect('kanban' in contentOf({ nodes })).toBe(false)
    const kanban = defaultKanbanFor('p')
    expect(contentOf({ nodes, kanban }).kanban).toBe(kanban)
  })
})

describe('diffContent', () => {
  it('replaying the diff reproduces next', () => {
    const prev: CanvasContent = { nodes: [node('a'), node('b')], bridges: [], ropes: [] }
    const next: CanvasContent = {
      nodes: [node('a', 5), node('c')],
      bridges: [{ id: 'x', source: 'a', target: 'c' }],
      ropes: [],
      kanban: { columns: [{ id: 'k1', title: 'T', color: '#000' }], assignments: [{ nodeId: 'a', columnId: 'k1' }] }
    }
    const replayed = diffContent(prev, next, 'p').reduce((c, m) => applyCanvasOp(c, m, 'p'), prev)
    expect(replayed.nodes).toEqual(next.nodes)
    expect(replayed.bridges).toEqual(next.bridges)
    expect(replayed.kanban?.assignments).toEqual(next.kanban?.assignments)
  })

  it('an identical content diffs to nothing', () => {
    const c: CanvasContent = { nodes: [node('a')], bridges: [{ id: 'x', source: 'a', target: 'a' }], ropes: [], kanban: defaultKanbanFor('p') }
    expect(diffContent(c, { ...c, nodes: [node('a')] }, 'p')).toEqual([])
  })

  it('orders the batch: node adds, then edges and board, then node removes', () => {
    const prev: CanvasContent = { nodes: [node('a'), node('gone')], bridges: [{ id: 'old', source: 'a', target: 'gone' }], ropes: [] }
    const next: CanvasContent = {
      nodes: [node('a'), node('new')],
      bridges: [],
      ropes: [{ id: 'r', source: 'a', target: 'new' }],
      kanban: { ...defaultKanbanFor('p'), assignments: [{ nodeId: 'new', columnId: defaultKanbanFor('p').columns[0].id }] }
    }
    const ops = diffContent(prev, next, 'p').map((m) => m.op)
    expect(ops).toEqual(['upsert', 'edge-upsert', 'edge-remove', 'kb-card', 'remove'])
  })

  // An outside edit (git pull, a hand edit) is not a lazy prune: a placement whose node is gone in
  // the NEW file was removed by someone, so the removal is cast — unlike a client's publisher, which
  // must not cast the prune of a card whose node op may simply not have arrived yet.
  it('casts the removal of a card whose node is gone (every removal is real)', () => {
    const k1 = { id: 'k1', title: 'T', color: '#000' }
    const prev: CanvasContent = {
      nodes: [node('a')],
      bridges: [],
      ropes: [],
      kanban: { columns: [k1], assignments: [{ nodeId: 'a', columnId: 'k1' }], meta: [{ nodeId: 'a', priority: 'high' }] }
    }
    const next: CanvasContent = { nodes: [], bridges: [], ropes: [], kanban: { columns: [k1], assignments: [], meta: [] } }
    const ops = diffContent(prev, next, 'p')
    expect(ops).toContainEqual({ op: 'kb-card-remove', nodeId: 'a' })
    expect(ops).toContainEqual({ op: 'kb-meta-remove', nodeId: 'a' })
    const replayed = ops.reduce((c, m) => applyCanvasOp(c, m, 'p'), prev)
    expect(replayed.kanban?.assignments).toEqual([])
    expect(replayed.kanban?.meta).toEqual([])
  })

  // A file with no `kanban` block renders as the project's lazy default on every client — so an
  // outside edit that REMOVED the block (a checkout from before the board was first edited) turns
  // every replica's board back into that default, instead of casting nothing and leaving each
  // client's old board in place over a file that no longer has one.
  it('a removed board diffs to the lazy default: every item list, not only columns and cards', () => {
    const prev: CanvasContent = {
      nodes: [node('a')],
      bridges: [],
      ropes: [],
      kanban: {
        columns: [{ id: 'k1', title: 'T', color: '#000' }],
        assignments: [{ nodeId: 'a', columnId: 'k1' }],
        meta: [{ nodeId: 'a', priority: 'high', labels: ['l1'] }],
        labels: [{ id: 'l1', name: 'Bug', color: 'red' }],
        views: [{ id: 'v1', name: 'Mine', query: {} } as never]
      }
    }
    const next: CanvasContent = { nodes: [node('a')], bridges: [], ropes: [] }
    const replayed = diffContent(prev, next, 'p').reduce((c, m) => applyCanvasOp(c, m, 'p'), prev)
    const fresh = defaultKanbanFor('p')
    expect(replayed.kanban?.columns).toEqual(fresh.columns)
    expect(replayed.kanban?.assignments).toEqual([])
    expect(replayed.kanban?.meta ?? []).toEqual([])
    expect(replayed.kanban?.labels ?? []).toEqual([])
    expect(replayed.kanban?.views ?? []).toEqual([])
    // …and a project that never had a board still casts nothing for it.
    expect(diffContent(next, { ...next }, 'p')).toEqual([])
  })

  // D12: the placement of a card whose node is gone on BOTH sides (a dead card the file still
  // carried) is removed when the outside edit drops it; before, `prev ∪ next` node ids were the only
  // live set, so every replica kept it.
  it('drops a dead card placement and its meta when the edit drops them', () => {
    const board = (withCard: boolean): ProjectKanban => ({
      ...defaultKanbanFor('p'),
      assignments: withCard ? [{ nodeId: 'gone', columnId: defaultKanbanFor('p').columns[0].id }] : [],
      ...(withCard ? { meta: [{ nodeId: 'gone', priority: 'low' as const }] } : {})
    })
    const prev: CanvasContent = { nodes: [node('a')], bridges: [], ropes: [], kanban: board(true) }
    const next: CanvasContent = { nodes: [node('a')], bridges: [], ropes: [], kanban: board(false) }
    const ops = diffContent(prev, next, 'p')
    expect(ops).toContainEqual({ op: 'kb-card-remove', nodeId: 'gone' })
    expect(ops).toContainEqual({ op: 'kb-meta-remove', nodeId: 'gone' })
  })
})