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.

18.7 KB
Raw Blame
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
import { promises as fs } from 'fs'
import os from 'os'
import path from 'path'
import { initPlatform, resetPlatformForTests } from './platform'
import { fakePlatform } from './platform-fake'
import { WorkspaceStore, type RemoteWorkspaceIO } from './workspace-store'
import { DEFAULT_BOARD_COLUMNS } from '../shared/kanban-default-board'
import type { Project, Workspace } from '../shared/types'

// The host side of the phone's Board sheet (`projects.ensureBoard` / `projects.setCardColumn`).
// Two project kinds, deliberately covered separately: a LOCAL ref writes its own file, and an SSH
// ref's file is on a third machine — the phone can never reach it, so the write lands in this
// desktop's cache and rides the ordinary mirror. That second half is the whole reason the verbs
// exist rather than more direct SSH from the phone.

let userData: string
let projRoot: string
let fake: ReturnType<typeof fakePlatform>

const project = (over: Partial<Project> = {}): Project => ({
  id: 'p1', name: 'foo', color: '#7aa2f7', viewport: { x: 0, y: 0, zoom: 1 },
  nodes: [{ id: 'term-1', kind: 'terminal', position: { x: 0, y: 0 }, size: { width: 1, height: 1 }, title: 't', color: '#fff', group: null }],
  ...over
})
const ws = (projects: Project[]): Workspace =>
  ({ version: 2, activeProjectId: projects[0]?.id ?? '', projects })
const SSH = { server: { host: 'h', user: 'u' }, remoteCwd: '~/x' } as unknown as Project['ssh']

const projectFile = (): string => path.join(projRoot, '.nodeterm/project.json')
const readFile = async (): Promise<Record<string, any>> =>
  JSON.parse(await fs.readFile(projectFile(), 'utf-8'))
const externalChanges = (): Record<string, any>[] =>
  fake.sent.filter((s) => s.channel === 'workspace:external-change').map((s) => s.args[0])

/** An ssh IO whose "server" is one in-memory string, so a mirror write is observable. */
function fakeRemote(initial: string | null = null): RemoteWorkspaceIO & { content: string | null; writes: number } {
  const io = {
    content: initial,
    writes: 0,
    async read() {
      return io.content === null
        ? ({ status: 'absent' } as const)
        : ({ status: 'ok', content: io.content } as const)
    },
    async write(_id: string, _ssh: never, content: string) {
      io.content = content
      io.writes++
      return true
    }
  }
  return io as never
}

beforeEach(async () => {
  userData = await fs.mkdtemp(path.join(os.tmpdir(), 'nt-ws-'))
  projRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'nt-proj-'))
  fake = fakePlatform({ userDataDir: userData })
  initPlatform(fake)
})
afterEach(async () => {
  resetPlatformForTests()
  await fs.rm(userData, { recursive: true, force: true })
  await fs.rm(projRoot, { recursive: true, force: true })
})

describe('ensureRemoteBoard (the phone creating a board that never existed)', () => {
  // The gap this closes: the desktop writes `kanban` only on the user's FIRST board edit, so most
  // project files have no board at all — and the phone, which knows a project only by its file,
  // showed no Board button on any of them.
  it('seeds the shared default columns into a local ref project file and announces it', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([project({ cwd: projRoot })]))
    expect((await readFile()).kanban).toBeUndefined()
    fake.sent.length = 0

    const columns = await store.ensureRemoteBoard('p1')
    expect(columns?.map((c) => c.title)).toEqual(DEFAULT_BOARD_COLUMNS.map((c) => c.title))
    expect(columns?.map((c) => c.color)).toEqual(DEFAULT_BOARD_COLUMNS.map((c) => c.color))

    const file = await readFile()
    expect(file.kanban.columns).toHaveLength(3)
    expect(file.rev).toBe(2)
    // Ours, and announced by us — the renderer must adopt it or the next autosave reverts it.
    expect(store.isSelfWrite(projectFile(), await fs.readFile(projectFile(), 'utf-8'))).toBe(true)
    expect(externalChanges()).toHaveLength(1)
    expect(externalChanges()[0].kanban.columns).toHaveLength(3)
  })

  it('is idempotent: an existing board comes back untouched, with no second write', async () => {
    const store = new WorkspaceStore()
    const kanban = { columns: [{ id: 'kcol-mine', title: 'Mine', color: '#fff' }], assignments: [] }
    await store.save(ws([project({ cwd: projRoot, kanban })]))
    const before = await readFile()

    const columns = await store.ensureRemoteBoard('p1')
    expect(columns).toEqual(kanban.columns)
    expect(await readFile()).toEqual(before) // rev included: no churn
  })

  it('refuses a project it cannot write a file for', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([project({ cwd: projRoot }), project({ id: 'inline1' })]))
    expect(await store.ensureRemoteBoard('nope')).toBeNull()
    expect(await store.ensureRemoteBoard('inline1')).toBeNull()
    await fs.writeFile(projectFile(), '{ not json')
    expect(await store.ensureRemoteBoard('p1')).toBeNull()
    expect(await fs.readFile(projectFile(), 'utf-8')).toBe('{ not json') // untouched
  })
})

describe('setRemoteCardColumn (the phone moving a card)', () => {
  const withBoard = (): Project =>
    project({
      cwd: projRoot,
      kanban: {
        columns: [
          { id: 'kcol-a', title: 'To Do', color: '#0a84ff' },
          { id: 'kcol-b', title: 'Done', color: '#32d74b' }
        ],
        assignments: []
      }
    })

  it('writes the assignment into a local ref project file and announces it', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([withBoard()]))
    fake.sent.length = 0

    expect(await store.setRemoteCardColumn('p1', 'term-1', 'kcol-b')).toBe(true)
    expect((await readFile()).kanban.assignments).toEqual([{ nodeId: 'term-1', columnId: 'kcol-b', rank: expect.any(String) }])
    expect(externalChanges()).toHaveLength(1)
    expect(externalChanges()[0].kanban.assignments).toEqual([{ nodeId: 'term-1', columnId: 'kcol-b', rank: expect.any(String) }])
  })

  it('null moves the card to Ungrouped', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([withBoard()]))
    await store.setRemoteCardColumn('p1', 'term-1', 'kcol-a')
    expect(await store.setRemoteCardColumn('p1', 'term-1', null)).toBe(true)
    expect((await readFile()).kanban.assignments).toEqual([])
  })

  // False is an ANSWER the phone shows the user, not a silent no-op — the behaviour this whole
  // change exists to remove.
  it('answers false, writing nothing, for an unknown column / project and a no-op move', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([withBoard()]))
    const before = await readFile()
    expect(await store.setRemoteCardColumn('p1', 'term-1', 'kcol-gone')).toBe(false)
    expect(await store.setRemoteCardColumn('nope', 'term-1', 'kcol-a')).toBe(false)
    expect(await store.setRemoteCardColumn('p1', 'term-1', null)).toBe(false) // already Ungrouped
    expect(await readFile()).toEqual(before)
  })

  it('leaves card metadata the phone cannot author alone', async () => {
    const store = new WorkspaceStore()
    const p = withBoard()
    p.kanban!.meta = [{ nodeId: 'term-1', priority: 'high', assignees: [], labels: [] } as never]
    await store.save(ws([p]))
    await store.setRemoteCardColumn('p1', 'term-1', 'kcol-a')
    expect((await readFile()).kanban.meta).toEqual([
      { nodeId: 'term-1', priority: 'high', assignees: [], labels: [] }
    ])
  })

  // The save chain is the same invariant appendRemoteNode documents: this rewrites the very file a
  // save rewrites whole, and unserialized the save's copy — which never saw the move — lands last.
  it('is serialized with saves', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([withBoard()]))
    const saving = store.save(ws([{ ...withBoard(), name: 'renamed' }]))
    const moving = store.setRemoteCardColumn('p1', 'term-1', 'kcol-a')
    expect(await moving).toBe(true)
    await saving
    const file = await readFile()
    expect(file.kanban.assignments).toEqual([{ nodeId: 'term-1', columnId: 'kcol-a', rank: expect.any(String) }])
    expect(file.name).toBe('renamed')
  })
})

describe('an SSH project (the case the phone can never write itself)', () => {
  // The phone reaches THIS desktop. An ssh ref's `.nodeterm/project.json` is on a third machine it
  // has no credentials for, so the write goes exactly where a desktop card drag's goes: into this
  // entry's cache, rev-bumped, then out on the ordinary mirror — which is why it needs nothing new
  // from `reconcileSsh` (that decides by rev and unions only `nodes`).
  const sshProject = (kanban?: Project['kanban']): Project =>
    project({ id: 'ssh1', cwd: undefined, ssh: SSH, ...(kanban ? { kanban } : {}) })

  it('seeds a board into the entry cache and mirrors it to the server', async () => {
    const io = fakeRemote()
    const store = new WorkspaceStore(io)
    await store.save(ws([sshProject()]))
    const mirrorsBefore = io.writes
    fake.sent.length = 0

    const columns = await store.ensureRemoteBoard('ssh1')
    expect(columns?.map((c) => c.title)).toEqual(DEFAULT_BOARD_COLUMNS.map((c) => c.title))
    expect(io.writes).toBeGreaterThan(mirrorsBefore)
    expect(JSON.parse(io.content!).kanban.columns).toHaveLength(3)
    // Announced, so the live canvas adopts it instead of the next autosave writing the old board back.
    expect(externalChanges()[0]).toMatchObject({ id: 'ssh1' })
    expect(externalChanges()[0].kanban.columns).toHaveLength(3)
  })

  it('moves a card and mirrors it, and the reloaded workspace carries the move', async () => {
    const io = fakeRemote()
    const store = new WorkspaceStore(io)
    await store.save(ws([sshProject({
      columns: [{ id: 'kcol-a', title: 'To Do', color: '#0a84ff' }],
      assignments: []
    })]))

    expect(await store.setRemoteCardColumn('ssh1', 'term-1', 'kcol-a')).toBe(true)
    expect(JSON.parse(io.content!).kanban.assignments).toEqual([{ nodeId: 'term-1', columnId: 'kcol-a', rank: expect.any(String) }])
    const reloaded = await new WorkspaceStore(io).load()
    expect(reloaded.projects.find((p) => p.id === 'ssh1')?.kanban?.assignments)
      .toEqual([{ nodeId: 'term-1', columnId: 'kcol-a', rank: expect.any(String) }])
  })

  // Every refusal reason stays a refusal on this path too — a cache write that cannot be described
  // as the requested change must not be mirrored as if it were.
  it('answers false for an unknown column and writes nothing', async () => {
    const io = fakeRemote()
    const store = new WorkspaceStore(io)
    await store.save(ws([sshProject({ columns: [{ id: 'kcol-a', title: 'To Do', color: '#0a84ff' }], assignments: [] })]))
    const mirrored = io.content
    const writes = io.writes
    expect(await store.setRemoteCardColumn('ssh1', 'term-1', 'kcol-gone')).toBe(false)
    expect(io.content).toBe(mirrored)
    expect(io.writes).toBe(writes)
  })

  // A mirror that cannot land (host asleep, dial flapped) must leave the change OWED, not lost: the
  // answer to the phone is about the board, and the next save retries the push. The save here
  // carries the board because the renderer ADOPTED the broadcast — which is the contract this path
  // depends on, and the reason the broadcast is not optional: a renderer that never heard about the
  // change would serialize its old board over it on the very next autosave.
  it('keeps the change when the mirror write fails, and a later save pushes it', async () => {
    const io = fakeRemote()
    let allowWrite = false
    const flaky = { ...io, write: async (id: string, ssh: never, content: string) => allowWrite && io.write(id, ssh, content) }
    const store = new WorkspaceStore(flaky as never)
    await store.save(ws([sshProject()]))
    fake.sent.length = 0

    expect(await store.ensureRemoteBoard('ssh1')).toHaveLength(3)
    expect(io.content).toBeNull() // nothing reached the server yet

    allowWrite = true
    const adopted = externalChanges()[0] as Project
    await store.save(ws([adopted]))
    expect(JSON.parse(io.content!).kanban.columns).toHaveLength(3)
  })

  // The ssh cache is not on this machine's disk as a project.json — it lives in workspace.json, so
  // a change kept only in memory is one an app restart silently drops.
  it('persists the cache change to the index, so a restart still has the board', async () => {
    const io = fakeRemote()
    const store = new WorkspaceStore(io)
    await store.save(ws([sshProject()]))
    await store.ensureRemoteBoard('ssh1')

    const index = JSON.parse(await fs.readFile(path.join(userData, 'workspace.json'), 'utf-8'))
    const entry = index.entries.find((x: { id: string }) => x.id === 'ssh1')
    expect(entry.cache.kanban.columns).toHaveLength(3)
  })

  // "Share with team": once the project is handed to a hosted team, the server core is the only
  // writer of its project.json. A phone board verb must be refused here, before the transform, so
  // the local cache never diverges and the renderer is never told about a change that will not land.
  it('refuses every board verb on a project handed to a hosted team: no read, no write, no broadcast', async () => {
    const io = fakeRemote()
    let reads = 0
    const store = new WorkspaceStore({ ...io, read: async (id: string, ssh: never) => { reads++; return io.read(id, ssh) } } as never)
    const handedOffTo = { hostId: 'h1', projectId: 'project-9', at: 1 }
    await store.save(ws([
      { ...sshProject({ columns: [{ id: 'kcol-a', title: 'To Do', color: '#0a84ff' }], assignments: [] }), handedOffTo },
      // A board-less one, so `ensureRemoteBoard` would have something to seed.
      project({ id: 'ssh2', cwd: undefined, ssh: { ...SSH!, remoteCwd: '~/y' }, handedOffTo })
    ]))
    const indexBefore = await fs.readFile(path.join(userData, 'workspace.json'), 'utf-8')
    fake.sent.length = 0

    expect(await store.setRemoteCardColumn('ssh1', 'term-1', 'kcol-a')).toBe(false)
    expect(await store.editRemoteCardLabels('ssh1', 'term-1', { create: [{ name: 'ui', color: 'blue' }] })).toBeNull()
    expect(await store.ensureRemoteBoard('ssh2')).toBeNull()

    expect(reads).toBe(0)
    expect(io.writes).toBe(0)
    expect(externalChanges()).toEqual([])
    expect(await fs.readFile(path.join(userData, 'workspace.json'), 'utf-8')).toBe(indexBefore)
  })
})

describe('editRemoteCardLabels (the phone labelling a session)', () => {
  // ONE label model: the palette in `kanban.labels` + ids in `kanban.meta[].labels`, the same the
  // canvas node's "+ Label" row and the kanban card write. These pin that a phone edit lands there,
  // is announced (so the live canvas adopts it rather than the next autosave reverting it), and that
  // a desktop-authored label comes back to the phone in the answer.
  const withLabels = (over: Partial<Project> = {}): Project =>
    project({
      cwd: projRoot,
      kanban: {
        columns: [{ id: 'kcol-a', title: 'To Do', color: '#0a84ff' }],
        assignments: [],
        labels: [{ id: 'klbl-bug', name: 'bug', color: 'red' }]
      },
      ...over
    })

  it('applies a desktop label to the card, writes the file and announces it', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([withLabels()]))
    fake.sent.length = 0

    const res = await store.editRemoteCardLabels('p1', 'term-1', { add: ['klbl-bug'] })
    expect(res).toEqual({
      edited: true,
      labels: [{ id: 'klbl-bug', name: 'bug', color: 'red' }],
      cardLabelIds: ['klbl-bug']
    })
    expect((await readFile()).kanban.meta).toEqual([{ nodeId: 'term-1', labels: ['klbl-bug'] }])
    expect(externalChanges()).toHaveLength(1)
    expect(externalChanges()[0].kanban.meta).toEqual([{ nodeId: 'term-1', labels: ['klbl-bug'] }])
  })

  it('the first label on a board-less project seeds the default board', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([project({ cwd: projRoot })]))
    const res = await store.editRemoteCardLabels('p1', 'term-1', { create: [{ name: 'ui', color: 'blue' }] })
    expect(res?.edited).toBe(true)
    expect(res?.labels.map((l) => l.name)).toEqual(['ui'])
    expect(res?.cardLabelIds).toEqual([res?.labels[0].id])
    expect((await readFile()).kanban.columns.map((c: { title: string }) => c.title))
      .toEqual(DEFAULT_BOARD_COLUMNS.map((c) => c.title))
  })

  it('a stale add is `edited:false` WITH the current palette, so the sheet can redraw', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([withLabels()]))
    const before = await readFile()
    const res = await store.editRemoteCardLabels('p1', 'term-1', { add: ['klbl-deleted-elsewhere'] })
    expect(res).toEqual({ edited: false, labels: [{ id: 'klbl-bug', name: 'bug', color: 'red' }], cardLabelIds: [] })
    expect(await readFile()).toEqual(before)
  })

  it('drops dangling ids from the answer exactly as the desktop readers do', async () => {
    const store = new WorkspaceStore()
    const p = withLabels()
    p.kanban!.meta = [{ nodeId: 'term-1', labels: ['klbl-bug', 'klbl-ghost'] }]
    await store.save(ws([p]))
    const res = await store.editRemoteCardLabels('p1', 'term-1', { add: ['klbl-bug'] })
    expect(res?.cardLabelIds).toEqual(['klbl-bug'])
  })

  it('answers null for a project it cannot write', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([withLabels(), project({ id: 'inline1' })]))
    expect(await store.editRemoteCardLabels('nope', 'term-1', { add: ['klbl-bug'] })).toBeNull()
    expect(await store.editRemoteCardLabels('inline1', 'term-1', { add: ['klbl-bug'] })).toBeNull()
  })

  it('is serialized with saves', async () => {
    const store = new WorkspaceStore()
    await store.save(ws([withLabels()]))
    const saving = store.save(ws([{ ...withLabels(), name: 'renamed' }]))
    const labelling = store.editRemoteCardLabels('p1', 'term-1', { add: ['klbl-bug'] })
    expect((await labelling)?.edited).toBe(true)
    await saving
    const file = await readFile()
    expect(file.kanban.meta).toEqual([{ nodeId: 'term-1', labels: ['klbl-bug'] }])
    expect(file.name).toBe('renamed')
  })

  it('an SSH project: writes the cache, mirrors it, and the reload carries the label', async () => {
    const io = fakeRemote()
    const store = new WorkspaceStore(io)
    await store.save(ws([project({
      id: 'ssh1', cwd: undefined, ssh: SSH,
      kanban: { columns: [{ id: 'kcol-a', title: 'To Do', color: '#0a84ff' }], assignments: [],
        labels: [{ id: 'klbl-bug', name: 'bug', color: 'red' }] }
    })]))
    const res = await store.editRemoteCardLabels('ssh1', 'term-1', { add: ['klbl-bug'] })
    expect(res?.edited).toBe(true)
    expect(JSON.parse(io.content!).kanban.meta).toEqual([{ nodeId: 'term-1', labels: ['klbl-bug'] }])
    const reloaded = await new WorkspaceStore(io).load()
    expect(reloaded.projects.find((p) => p.id === 'ssh1')?.kanban?.meta)
      .toEqual([{ nodeId: 'term-1', labels: ['klbl-bug'] }])
  })
})