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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { describe, expect, it, beforeEach, afterEach } from 'vitest'
import { promises as fs } from 'fs'
import { mkdtemp, rm } from 'fs/promises'
import { tmpdir } from 'os'
import { join } from 'path'
import {
WHITEBOARD_SCENE_MAX_BYTES,
appWhiteboardsDir,
carryWhiteboards,
projectWhiteboardsDir,
readWhiteboard,
saveWhiteboard
} from './whiteboards'
const scene = JSON.stringify({ type: 'excalidraw', elements: [{ id: 'a' }] })
// Bytes that utf-8 text encoding would mangle (0x89 'PNG' header, a NUL, high bytes).
const pngBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0xff, 0xfe, 0x80])
const png = pngBytes.toString('base64')
/** The written path of a successful save (the tests above the compare-and-set block do not care
* about revisions). */
const pathOf = (r: Awaited<ReturnType<typeof saveWhiteboard>>): string | null => (r && r.ok ? r.path : null)
let root: string
let userDataDir: string
let projectCwd: string
beforeEach(async () => {
root = await mkdtemp(join(tmpdir(), 'nt-whiteboards-'))
userDataDir = join(root, 'userData')
projectCwd = join(root, 'project')
await fs.mkdir(projectCwd, { recursive: true })
})
afterEach(() => rm(root, { recursive: true, force: true }))
describe('saveWhiteboard / readWhiteboard', () => {
it('writes beside project.json and reads the scene and picture back, picture byte-exact', async () => {
const path = await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene, png)
expect(pathOf(path)).toBe(join(projectWhiteboardsDir(projectCwd), 'whiteboard-1.excalidraw'))
const read = await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1')
expect(read).toMatchObject({ scene, fromSource: false })
expect(Buffer.from(read!.thumbnailBase64!, 'base64').equals(pngBytes)).toBe(true)
expect(read!.updatedAt).toBeGreaterThan(0)
})
it('uses the app folder for a project with no local cwd (cwd-less canvas, SSH project)', async () => {
const path = await saveWhiteboard({ userDataDir }, 'whiteboard-1', scene)
expect(pathOf(path)).toBe(join(appWhiteboardsDir(userDataDir), 'whiteboard-1.excalidraw'))
expect((await readWhiteboard({ userDataDir }, 'whiteboard-1'))?.scene).toBe(scene)
})
it('never resurrects a deleted project folder; the board lands in the app folder instead', async () => {
await rm(projectCwd, { recursive: true, force: true })
const path = await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene)
expect(pathOf(path)).toBe(join(appWhiteboardsDir(userDataDir), 'whiteboard-1.excalidraw'))
await expect(fs.stat(projectCwd)).rejects.toThrow()
})
it('falls back to the app folder when the project folder will not take the file', async () => {
await fs.writeFile(join(projectCwd, '.nodeterm'), 'not a directory')
const path = await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene)
expect(pathOf(path)).toBe(join(appWhiteboardsDir(userDataDir), 'whiteboard-1.excalidraw'))
// ...and a read finds it there, since the project folder has no board.
expect((await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1'))?.scene).toBe(scene)
})
it('refuses any id that could name a path, for both write and read', async () => {
for (const bad of ['../escape', 'a/b', 'a\\b', '..', '', '.', 42 as unknown as string]) {
expect(await saveWhiteboard({ projectCwd, userDataDir }, bad, scene)).toBeNull()
expect(await readWhiteboard({ projectCwd, userDataDir }, bad)).toBeNull()
}
expect(await fs.readdir(root)).toEqual(['project'])
})
it('refuses a scene over the cap rather than truncating it', async () => {
const big = 'x'.repeat(WHITEBOARD_SCENE_MAX_BYTES + 1)
expect(await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', big)).toBeNull()
})
it('a copied node reads its source until it saves its own board', async () => {
await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-orig', scene, png)
const copy = await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-copy', 'whiteboard-orig')
expect(copy).toMatchObject({ scene, fromSource: true })
const edited = JSON.stringify({ type: 'excalidraw', elements: [] })
await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-copy', edited)
expect(await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-copy', 'whiteboard-orig')).toMatchObject({
scene: edited,
fromSource: false
})
// The source is untouched by the copy's save.
expect((await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-orig'))?.scene).toBe(scene)
})
it('ignores an unsafe source id instead of following it', async () => {
expect(await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', '../../etc/passwd')).toBeNull()
})
it('an empty picture means the board was cleared: the old picture is removed, not kept', async () => {
await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene, png)
await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene, '')
expect((await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1'))?.thumbnailBase64).toBeUndefined()
})
it('a picture-only read (a board at rest) skips the scene but keeps the picture and revision', async () => {
await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene, png)
const rest = await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', undefined, false)
expect(rest?.scene).toBeUndefined()
expect(rest?.thumbnailBase64).toBe(png)
expect(rest?.updatedAt).toBeGreaterThan(0)
})
it.skipIf(process.platform === 'win32')(
'never follows a symlinked board file (a crafted repo cannot point a board at another file)',
async () => {
const secret = join(root, 'secret.txt')
await fs.writeFile(secret, 'private key material')
const dir = projectWhiteboardsDir(projectCwd)
await fs.mkdir(dir, { recursive: true })
await fs.symlink(secret, join(dir, 'whiteboard-evil.excalidraw'))
await fs.symlink(secret, join(dir, 'whiteboard-evil.png'))
expect(await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-evil')).toBeNull()
}
)
it('answers null for a board that was never saved (a new, empty board)', async () => {
expect(await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-new')).toBeNull()
})
})
// `.nodeterm/` is git-shared, so a cloned repository can commit `.nodeterm/whiteboards` (or
// `.nodeterm` itself) as a symlink to anywhere on this machine. The file-level no-follow read above
// does not cover that: every path component before the file name is still followed.
describe.skipIf(process.platform === 'win32')('the project folder is bound by its real path', () => {
let outside: string
beforeEach(async () => {
outside = join(root, 'outside')
await fs.mkdir(outside)
})
it('a .nodeterm/whiteboards symlink out of the project: nothing is written through it', async () => {
await fs.mkdir(join(projectCwd, '.nodeterm'))
await fs.symlink(outside, projectWhiteboardsDir(projectCwd))
const path = await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene, png)
expect(pathOf(path)).toBe(join(appWhiteboardsDir(userDataDir), 'whiteboard-1.excalidraw'))
expect(await fs.readdir(outside)).toEqual([])
})
it('a .nodeterm symlink out of the project: no folder is created on the other side', async () => {
await fs.symlink(outside, join(projectCwd, '.nodeterm'))
const path = await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene, png)
expect(pathOf(path)).toBe(join(appWhiteboardsDir(userDataDir), 'whiteboard-1.excalidraw'))
expect(await fs.readdir(outside)).toEqual([])
})
it('a read never follows a symlinked folder out of the project', async () => {
await fs.writeFile(join(outside, 'whiteboard-x.excalidraw'), scene)
await fs.writeFile(join(outside, 'whiteboard-x.png'), pngBytes)
await fs.mkdir(join(projectCwd, '.nodeterm'))
await fs.symlink(outside, projectWhiteboardsDir(projectCwd))
expect(await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-x')).toBeNull()
// ...and neither does a copy's read of its source through the same folder.
expect(await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-y', 'whiteboard-x')).toBeNull()
})
it('a symlink that stays inside the project is followed', async () => {
await fs.mkdir(join(projectCwd, 'boards'))
await fs.mkdir(join(projectCwd, '.nodeterm'))
await fs.symlink(join(projectCwd, 'boards'), projectWhiteboardsDir(projectCwd))
expect(await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene)).not.toBeNull()
expect(await fs.readFile(join(projectCwd, 'boards', 'whiteboard-1.excalidraw'), 'utf8')).toBe(scene)
expect((await readWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1'))?.scene).toBe(scene)
})
it('a project folder opened through a symlink still keeps its boards in the project', async () => {
const linked = join(root, 'linked-project')
await fs.symlink(projectCwd, linked)
expect(await saveWhiteboard({ projectCwd: linked, userDataDir }, 'whiteboard-1', scene)).not.toBeNull()
expect(await fs.readFile(join(projectWhiteboardsDir(projectCwd), 'whiteboard-1.excalidraw'), 'utf8')).toBe(scene)
expect(await fs.readdir(join(root, 'userData')).catch(() => [])).toEqual([])
})
})
// A board can be open in two places at once: two Server Edition tabs, the desktop and a browser on
// one folder, two Editors of a hosted team. Each save names the revision its editor last read or
// wrote, and the core refuses a save whose revision is no longer the one on disk — instead of the
// later writer silently replacing the earlier writer's whole board.
describe('compare-and-set: a save made against a stale revision is refused', () => {
const sceneOf = (tag: string) => JSON.stringify({ type: 'excalidraw', elements: [{ id: tag }] })
const onDisk = () => fs.readFile(join(projectWhiteboardsDir(projectCwd), 'whiteboard-1.excalidraw'), 'utf8')
it('the second of two editors that opened the same board cannot overwrite the first', async () => {
const loc = { projectCwd, userDataDir }
await saveWhiteboard(loc, 'whiteboard-1', sceneOf('start'))
const a = await readWhiteboard(loc, 'whiteboard-1')
const b = await readWhiteboard(loc, 'whiteboard-1')
expect(a?.rev).toBeTruthy()
expect(a?.rev).toBe(b?.rev)
const savedB = await saveWhiteboard(loc, 'whiteboard-1', sceneOf('b'), undefined, b!.rev)
expect(savedB).toMatchObject({ ok: true })
const savedA = await saveWhiteboard(loc, 'whiteboard-1', sceneOf('a'), undefined, a!.rev)
expect(savedA).toMatchObject({ ok: false, conflict: true, currentRev: (savedB as { rev: string }).rev })
expect(await onDisk()).toBe(sceneOf('b'))
})
it('a save returns the new revision, and saving again against it succeeds', async () => {
const loc = { projectCwd, userDataDir }
const first = await saveWhiteboard(loc, 'whiteboard-1', sceneOf('1'), undefined, null)
expect(first).toMatchObject({ ok: true })
const rev = (first as { rev: string }).rev
expect((await readWhiteboard(loc, 'whiteboard-1'))?.rev).toBe(rev)
expect(await saveWhiteboard(loc, 'whiteboard-1', sceneOf('2'), undefined, rev)).toMatchObject({ ok: true })
expect(await onDisk()).toBe(sceneOf('2'))
})
it('a null revision means "I have no board of my own": one that appeared meanwhile is kept', async () => {
const loc = { projectCwd, userDataDir }
await saveWhiteboard(loc, 'whiteboard-1', sceneOf('theirs'))
expect(await saveWhiteboard(loc, 'whiteboard-1', sceneOf('mine'), undefined, null)).toMatchObject({
ok: false,
conflict: true
})
expect(await onDisk()).toBe(sceneOf('theirs'))
})
it('the revision changes on every write, even a same-size rewrite in the same millisecond', async () => {
const loc = { projectCwd, userDataDir }
const revs = new Set<string>()
for (const tag of ['aa', 'bb', 'cc']) {
const saved = await saveWhiteboard(loc, 'whiteboard-1', sceneOf(tag))
revs.add((saved as { rev: string }).rev)
}
expect(revs.size).toBe(3)
})
it('two saves racing in one core are serialized: exactly one of them wins', async () => {
const loc = { projectCwd, userDataDir }
const start = await saveWhiteboard(loc, 'whiteboard-1', sceneOf('start'))
const rev = (start as { rev: string }).rev
const results = await Promise.all([
saveWhiteboard(loc, 'whiteboard-1', sceneOf('x'), undefined, rev),
saveWhiteboard(loc, 'whiteboard-1', sceneOf('y'), undefined, rev)
])
expect(results.filter((r) => r && 'ok' in r && r.ok)).toHaveLength(1)
expect(results.filter((r) => r && 'conflict' in r)).toHaveLength(1)
})
it('no revision at all (an older caller) keeps the unconditional write', async () => {
const loc = { projectCwd, userDataDir }
await saveWhiteboard(loc, 'whiteboard-1', sceneOf('one'))
expect(await saveWhiteboard(loc, 'whiteboard-1', sceneOf('two'))).toMatchObject({ ok: true })
expect(await onDisk()).toBe(sceneOf('two'))
})
})
// A folder project can keep its canvas in app data (issue #1145) so that nothing is written into
// the folder. Its boards then live in the project's own app-data root (`appDataProjectRoot` in
// workspace-store.ts), and the folder's boards — drawn before the move — are only ever READ.
describe('a folder project kept in app data', () => {
let appRoot: string
beforeEach(() => {
appRoot = join(userDataDir, 'project-files', 'project-p1')
})
it("writes into the project's app-data root, creating it, and nothing into the folder", async () => {
const loc = { projectCwd: appRoot, createRoot: true, readOnlyRoot: projectCwd, userDataDir }
const saved = await saveWhiteboard(loc, 'whiteboard-1', scene, png)
expect(pathOf(saved)).toBe(join(projectWhiteboardsDir(appRoot), 'whiteboard-1.excalidraw'))
expect(await fs.readdir(projectCwd)).toEqual([])
expect((await readWhiteboard(loc, 'whiteboard-1'))?.scene).toBe(scene)
})
it('a board drawn in the folder before the move still opens, and its next save lands in app data', async () => {
await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene, png)
const loc = { projectCwd: appRoot, createRoot: true, readOnlyRoot: projectCwd, userDataDir }
const before = await readWhiteboard(loc, 'whiteboard-1')
expect(before).toMatchObject({ scene, fromSource: false })
const edited = JSON.stringify({ type: 'excalidraw', elements: [{ id: 'b' }] })
// Saved against the folder file's revision: the compare-and-set sees the same board the read did.
expect(await saveWhiteboard(loc, 'whiteboard-1', edited, png, before!.rev)).toMatchObject({ ok: true })
expect((await readWhiteboard(loc, 'whiteboard-1'))?.scene).toBe(edited)
expect(await fs.readFile(join(projectWhiteboardsDir(projectCwd), 'whiteboard-1.excalidraw'), 'utf8')).toBe(scene)
})
it('never writes into the read-only root, even when the app-data root will not take the board', async () => {
await fs.mkdir(userDataDir, { recursive: true })
await fs.writeFile(join(userDataDir, 'project-files'), 'not a directory')
const loc = { projectCwd: appRoot, createRoot: true, readOnlyRoot: projectCwd, userDataDir }
const saved = await saveWhiteboard(loc, 'whiteboard-1', scene)
expect(pathOf(saved)).toBe(join(appWhiteboardsDir(userDataDir), 'whiteboard-1.excalidraw'))
expect(await fs.readdir(projectCwd)).toEqual([])
})
it('reads every place a save can land before the read-only root, so a save is never shadowed', async () => {
// The folder still holds the board as it was before the move…
await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene)
// …and the app-data root cannot take the edit, so it falls back to the app folder.
await fs.mkdir(userDataDir, { recursive: true })
await fs.writeFile(join(userDataDir, 'project-files'), 'not a directory')
const loc = { projectCwd: appRoot, createRoot: true, readOnlyRoot: projectCwd, userDataDir }
const edited = JSON.stringify({ type: 'excalidraw', elements: [{ id: 'b' }] })
await saveWhiteboard(loc, 'whiteboard-1', edited)
expect((await readWhiteboard(loc, 'whiteboard-1'))?.scene).toBe(edited)
})
})
// The move of a folder project's canvas from app data back into its folder (issue #1145) takes the
// boards drawn or edited in app data along: the folder is read first afterwards, and its older file
// of the same board would otherwise hide the newer one.
describe('carryWhiteboards', () => {
let appRoot: string
beforeEach(() => {
appRoot = join(userDataDir, 'project-files', 'project-p1')
})
const inFolder = (name: string) => join(projectWhiteboardsDir(projectCwd), name)
it("copies every board into the folder, replacing the folder's older file, picture byte-exact", async () => {
const edited = JSON.stringify({ type: 'excalidraw', elements: [{ id: 'edited' }] })
await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene)
await saveWhiteboard({ projectCwd: appRoot, createRoot: true, userDataDir }, 'whiteboard-1', edited, png)
await saveWhiteboard({ projectCwd: appRoot, createRoot: true, userDataDir }, 'whiteboard-2', scene)
await carryWhiteboards(appRoot, projectCwd)
expect(await fs.readFile(inFolder('whiteboard-1.excalidraw'), 'utf8')).toBe(edited)
expect((await fs.readFile(inFolder('whiteboard-1.png'))).equals(pngBytes)).toBe(true)
expect(await fs.readFile(inFolder('whiteboard-2.excalidraw'), 'utf8')).toBe(scene)
// The app-data copies stay: nothing is deleted on either side.
expect(await fs.readFile(join(projectWhiteboardsDir(appRoot), 'whiteboard-1.excalidraw'), 'utf8')).toBe(edited)
})
it("a carried board with no picture drops the folder's old picture rather than show it", async () => {
await saveWhiteboard({ projectCwd, userDataDir }, 'whiteboard-1', scene, png)
await saveWhiteboard({ projectCwd: appRoot, createRoot: true, userDataDir }, 'whiteboard-1', scene, '')
await carryWhiteboards(appRoot, projectCwd)
await expect(fs.stat(inFolder('whiteboard-1.png'))).rejects.toThrow()
})
it('does nothing, and creates nothing in the folder, when there is no board to carry', async () => {
await carryWhiteboards(appRoot, projectCwd)
expect(await fs.readdir(projectCwd)).toEqual([])
})
it.skipIf(process.platform === 'win32')('never carries a symlink, and never writes through one', async () => {
const secret = join(root, 'secret.txt')
await fs.writeFile(secret, 'private key material')
const from = projectWhiteboardsDir(appRoot)
await fs.mkdir(from, { recursive: true })
await fs.symlink(secret, join(from, 'whiteboard-evil.excalidraw'))
await carryWhiteboards(appRoot, projectCwd)
await expect(fs.stat(inFolder('whiteboard-evil.excalidraw'))).rejects.toThrow()
const outside = join(root, 'outside')
await fs.mkdir(outside)
await saveWhiteboard({ projectCwd: appRoot, createRoot: true, userDataDir }, 'whiteboard-1', scene)
await fs.mkdir(join(projectCwd, '.nodeterm'), { recursive: true })
await fs.symlink(outside, projectWhiteboardsDir(projectCwd))
await carryWhiteboards(appRoot, projectCwd)
expect(await fs.readdir(outside)).toEqual([])
})
})