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 {
descendantIds,
displacedByWorktree,
isAncestorPath,
isInsideDir,
worktreePathKey,
sanitizeWorktreeBranch,
computeWorktreePath,
resolveWorktreePath,
parseWorktreePorcelain,
isDangerousWorktreeRemovalPath,
decideMergeStrategy,
isRemoteSessionNode,
isValidGitRef,
resolveBaseRef,
resolveWorktreeBase,
type WorktreeBaseNode,
worktreeFromCreate,
worktreeFromEntry,
worktreeRemoveMessage,
effectiveWorktreeBaseRef,
effectiveWorktreeTemplate,
DEFAULT_BASE_REF,
DEFAULT_WORKTREE_PATH_TEMPLATE,
type WorktreeEntry,
type ProjectWorktreeDefaults
} from './worktree'
import { filterWorktrees } from './worktree'
const entry = (path: string, branch: string | null): WorktreeEntry => ({
path,
branch,
head: 'abc',
isBare: false
})
// Worktrees are local-only in v1, and the gate that keeps a remote session out of one must ask
// about BOTH SSH markers: the exact node it exists to protect — an SSH-PROJECT terminal, created by
// `createTerminalNode(…, project.ssh)` with `data.ssh` + `data.sshRemoteTmux` — once walked straight
// through a one-field guard: ↪ destroyed its REMOTE tmux session (running processes and all) and
// respawned it in a local path that does not exist on the host.
describe('isRemoteSessionNode', () => {
it('is true for an SSH-project terminal (data.ssh + data.sshRemoteTmux)', () => {
expect(
isRemoteSessionNode({
ssh: { host: 'box', user: 'me' },
sshRemoteTmux: true
})
).toBe(true)
})
it('is true when only one of the two SSH markers survived a hand-edited project file', () => {
expect(isRemoteSessionNode({ ssh: { host: 'box', user: 'me' } })).toBe(true)
expect(isRemoteSessionNode({ sshRemoteTmux: true })).toBe(true)
})
it('is false for a plain local terminal (nothing changes for the local case)', () => {
expect(isRemoteSessionNode({})).toBe(false)
expect(isRemoteSessionNode(undefined)).toBe(false)
expect(isRemoteSessionNode({ ssh: undefined, sshRemoteTmux: false })).toBe(false)
})
})
describe('isValidGitRef', () => {
it('accepts a normal branch name', () => {
expect(isValidGitRef('feature/x')).toBe(true)
})
it('rejects flag-injection and whitespace', () => {
expect(isValidGitRef('--force')).toBe(false)
expect(isValidGitRef('a b')).toBe(false)
expect(isValidGitRef('')).toBe(false)
})
})
describe('sanitizeWorktreeBranch', () => {
it('replaces spaces and illegal chars with dashes', () => {
expect(sanitizeWorktreeBranch('My Feature!')).toBe('my-feature')
})
it('strips leading dashes (flag-injection guard)', () => {
expect(sanitizeWorktreeBranch('--force')).toBe('force')
})
})
describe('computeWorktreePath', () => {
it('defaults beside the repository and flattens the branch', () => {
expect(computeWorktreePath('/src/myrepo', 'feature/x')).toBe(
'/src/myrepo.worktrees/feature-x'
)
})
it('supports the requested aliases and appends a branch when the template omits it', () => {
expect(computeWorktreePath('/src/MyRepo', 'Feature/X', '../$reponame.worktrees')).toBe(
'/src/MyRepo.worktrees/feature-x'
)
expect(computeWorktreePath('/src/MyRepo', 'Feature/X', '../$defaultFolderName.worktrees')).toBe(
'/src/MyRepo.worktrees/feature-x'
)
expect(computeWorktreePath('/src/MyRepo', 'Feature/X', './worktrees')).toBe(
'/src/MyRepo/worktrees/feature-x'
)
})
it('supports explicit branch tokens, absolute templates, and Windows-style input', () => {
expect(computeWorktreePath('/src/repo/', 'topic/a', '/tmp/wt/$branch')).toBe(
'/tmp/wt/topic-a'
)
expect(computeWorktreePath('C:\\src\\repo', 'topic/a', '..\\${repoName}.wt\\${branch}')).toBe(
'C:/src/repo.wt/topic-a'
)
})
it('suggests nothing when the repository or branch is unknown', () => {
expect(computeWorktreePath('', 'x')).toBe('')
expect(computeWorktreePath(' ', 'x')).toBe('')
expect(computeWorktreePath('/src/repo', '')).toBe('')
})
it('refuses a template that climbs past the repo to the filesystem root', () => {
// `../../../../..` clamps at `/`, which on a root-running Server Edition would make
// `git worktree add` create a directory at the filesystem root. Suggest nothing instead.
expect(computeWorktreePath('/src/repo', 'topic/a', '../../../../../..')).toBe('')
// One level under root is still refused (a single top-level segment).
expect(computeWorktreePath('/repo', 'b', '/${branch}')).toBe('')
// But a legitimate absolute base with depth is allowed.
expect(computeWorktreePath('/src/repo', 'b', '/srv/worktrees/${branch}')).toBe(
'/srv/worktrees/b'
)
})
})
describe('resolveWorktreePath', () => {
it('derives the configured default relative to the session repository root', async () => {
const p = await resolveWorktreePath({
repoRoot: '/srv/repos/myapp',
branch: 'feature/x',
template: './worktrees'
})
expect(p).toBe('/srv/repos/myapp/worktrees/feature-x')
})
it('honors an explicit --path', async () => {
const p = await resolveWorktreePath({
explicitPath: ' /custom/wt ',
repoRoot: '/srv/repos/x',
branch: 'b'
})
expect(p).toBe('/custom/wt')
})
it('yields "" when the repository root is unknown and no --path was given', async () => {
const p = await resolveWorktreePath({
repoRoot: '',
branch: 'b'
})
expect(p).toBe('')
})
})
describe('resolveBaseRef', () => {
it("uses the main checkout's branch — git prints it first", () => {
expect(resolveBaseRef([entry('/repo', 'trunk'), entry('/wt/x', 'feature/x')])).toBe('trunk')
expect(resolveBaseRef([entry('/repo', 'master')])).toBe('master')
})
it('falls back to main when the default branch is unknown (detached / empty list)', () => {
expect(resolveBaseRef([])).toBe(DEFAULT_BASE_REF)
expect(resolveBaseRef([entry('/repo', null)])).toBe(DEFAULT_BASE_REF)
expect(resolveBaseRef([entry('/repo', ' ')])).toBe(DEFAULT_BASE_REF)
})
})
describe('worktreeFromCreate', () => {
it('marks a worktree the app just created as createdByApp (Remove may delete the dir)', () => {
expect(
worktreeFromCreate({
repoPath: '/repo',
mode: 'new',
branch: 'feature/x',
baseRef: 'master',
path: '/u/worktrees/repo/feature-x'
})
).toEqual({
repoPath: '/repo',
branch: 'feature/x',
baseRef: 'master',
path: '/u/worktrees/repo/feature-x',
createdByApp: true
})
})
it("stores a Windows path '/'-separated, case kept, the shape git prints", () => {
expect(
worktreeFromCreate({ repoPath: 'C:\\r', mode: 'new', branch: 'b', baseRef: 'main', path: 'C:\\r.worktrees\\B' }).path
).toBe('C:/r.worktrees/B')
})
it('leaves a POSIX path with a backslash in a name untouched', () => {
expect(
worktreeFromCreate({ repoPath: '/r', mode: 'new', branch: 'b', baseRef: 'main', path: '/r.worktrees/a\\b' }).path
).toBe('/r.worktrees/a\\b')
})
it('trims the collected fields', () => {
const wt = worktreeFromCreate({
repoPath: ' /repo ',
mode: 'existing',
branch: ' feature/x ',
baseRef: ' main ',
path: ' /wt/x '
})
expect(wt).toMatchObject({ repoPath: '/repo', branch: 'feature/x', baseRef: 'main', path: '/wt/x' })
})
})
describe('worktreeFromEntry', () => {
it('marks an ADOPTED worktree as NOT createdByApp (Remove must not delete the user\'s dir)', () => {
const wt = worktreeFromEntry(entry('/wt/x', 'feature/x'), '/repo', 'trunk')
expect(wt).toEqual({
repoPath: '/repo',
branch: 'feature/x',
baseRef: 'trunk',
path: '/wt/x',
createdByApp: false
})
})
it('defaults the base ref to main when the repo default is unknown', () => {
expect(worktreeFromEntry(entry('/wt/x', 'feature/x'), '/repo', '')?.baseRef).toBe(DEFAULT_BASE_REF)
})
it('refuses a detached worktree or a missing repo root', () => {
expect(worktreeFromEntry(entry('/wt/x', null), '/repo', 'main')).toBeNull()
expect(worktreeFromEntry(entry('/wt/x', 'b'), '', 'main')).toBeNull()
expect(worktreeFromEntry(entry('', 'b'), '/repo', 'main')).toBeNull()
})
})
describe('parseWorktreePorcelain', () => {
it('parses git worktree list --porcelain blocks', () => {
const out = [
'worktree /repo', 'HEAD abc123', 'branch refs/heads/main', '',
'worktree /wt/x', 'HEAD def456', 'branch refs/heads/feature/x', '',
'worktree /bare', 'bare', ''
].join('\n')
const entries = parseWorktreePorcelain(out)
expect(entries).toEqual([
{ path: '/repo', head: 'abc123', branch: 'main', isBare: false, prunable: false },
{ path: '/wt/x', head: 'def456', branch: 'feature/x', isBare: false, prunable: false },
{ path: '/bare', head: null, branch: null, isBare: true, prunable: false }
])
})
// git keeps LISTING a worktree whose directory was deleted behind its back, tagging it
// `prunable`. Dropping that tag is what would let a dead worktree render as a healthy one.
it('flags a worktree whose directory is gone as prunable', () => {
const out = [
'worktree /repo', 'HEAD abc123', 'branch refs/heads/main', '',
'worktree /wt/gone', 'HEAD def456', 'branch refs/heads/feat',
'prunable gitdir file points to non-existent location', ''
].join('\n')
const entries = parseWorktreePorcelain(out)
expect(entries[0].prunable).toBe(false)
expect(entries[1]).toEqual({
path: '/wt/gone', head: 'def456', branch: 'feat', isBare: false, prunable: true
})
})
it('flags a bare `prunable` line with no reason', () => {
const entries = parseWorktreePorcelain(['worktree /wt/gone', 'prunable', ''].join('\n'))
expect(entries[0].prunable).toBe(true)
})
})
describe('isDangerousWorktreeRemovalPath', () => {
const home = '/Users/me'
it('refuses the repo root itself', () => {
expect(isDangerousWorktreeRemovalPath('/repo', '/repo', home)).toBe(true)
})
it('refuses a path that contains the repo', () => {
expect(isDangerousWorktreeRemovalPath('/repo', '/repo/sub', home)).toBe(true)
})
it('refuses home and filesystem root', () => {
expect(isDangerousWorktreeRemovalPath(home, '/repo', home)).toBe(true)
expect(isDangerousWorktreeRemovalPath('/', '/repo', home)).toBe(true)
})
it('allows a normal sibling worktree dir', () => {
expect(isDangerousWorktreeRemovalPath('/Users/me/worktrees/r/feature-x', '/repo', home)).toBe(false)
})
})
describe('worktreePathKey (Windows-shaped paths compare by identity, POSIX by exact case)', () => {
it('folds separators, trailing slashes, drive-letter and path case for Windows paths', () => {
expect(worktreePathKey('C:\\r\\wt\\')).toBe('c:/r/wt')
expect(worktreePathKey('c:/R/Wt')).toBe(worktreePathKey('C:\\r\\wt'))
expect(worktreePathKey('\\\\server\\share\\Wt')).toBe('//server/share/wt')
})
it('keeps a POSIX path byte-identical to the old trailing-slash strip', () => {
expect(worktreePathKey('/A/wt/')).toBe('/A/wt')
expect(worktreePathKey('/A/wt')).not.toBe(worktreePathKey('/a/wt'))
expect(worktreePathKey(' /x ')).toBe('/x')
})
it('does not fold a POSIX path that merely contains a backslash (a legal filename char there)', () => {
expect(worktreePathKey('/home/u/A\\b/')).toBe('/home/u/A\\b')
expect(worktreePathKey('/home/u/A\\b')).not.toBe(worktreePathKey('/home/u/a/b'))
expect(isAncestorPath('/home/u/a', '/home/u/A\\b')).toBe(false)
})
it('isAncestorPath matches across separators and case on Windows paths only', () => {
expect(isAncestorPath('C:/Users', 'C:\\Users\\x')).toBe(true)
expect(isAncestorPath('c:\\users\\', 'C:/Users/x/y')).toBe(true)
expect(isAncestorPath('C:/Users', 'C:/Users2')).toBe(false)
expect(isAncestorPath('/Users', '/users/x')).toBe(false)
expect(isAncestorPath('/', '/x')).toBe(true)
})
})
describe('isDangerousWorktreeRemovalPath on Windows paths', () => {
it('refuses home spelled with the other separator or case', () => {
expect(isDangerousWorktreeRemovalPath('C:/Users/x', 'C:/r', 'C:\\Users\\x')).toBe(true)
expect(isDangerousWorktreeRemovalPath('c:/users', 'C:/r', 'C:\\Users\\x')).toBe(true)
expect(isDangerousWorktreeRemovalPath('C:\\R', 'c:/r', 'C:\\Users\\x')).toBe(true)
})
it('refuses a bare drive root in every spelling', () => {
for (const root of ['C:/', 'C:\\', 'c:', 'D:\\']) {
expect(isDangerousWorktreeRemovalPath(root, 'E:/r', 'E:/Users/x')).toBe(true)
}
})
it('allows a sibling worktree', () => {
expect(isDangerousWorktreeRemovalPath('C:/r.worktrees/feat', 'C:/r', 'C:\\Users\\x')).toBe(false)
})
})
describe('decideMergeStrategy', () => {
it('fetch-updates when base is not checked out anywhere', () => {
expect(decideMergeStrategy({ baseCheckedOutPath: null, baseDirty: false }))
.toEqual({ kind: 'fetch-update' })
})
it('merges in place when base checkout is clean', () => {
expect(decideMergeStrategy({ baseCheckedOutPath: '/repo', baseDirty: false }))
.toEqual({ kind: 'merge-in-place', path: '/repo' })
})
it('blocks when base checkout is dirty', () => {
const r = decideMergeStrategy({ baseCheckedOutPath: '/repo', baseDirty: true })
expect(r.kind).toBe('blocked')
})
})
// Removing a worktree has to reach every node that was living in its directory — a terminal inside
// a NESTED group is in that directory just as much as a direct child; editor/diff nodes are
// with it too. A one-level filter left them holding a dead cwd, which is the exact trap the
// destructive-edges work exists to remove.
describe('descendantIds', () => {
const nodes = [
{ id: 'g' },
{ id: 't1', parentId: 'g' },
{ id: 'inner', parentId: 'g' },
{ id: 't2', parentId: 'inner' }, // two levels down
{ id: 'deep', parentId: 't2' },
{ id: 'outside' }
]
it('collects children AND grandchildren, never a node outside the group', () => {
expect([...descendantIds(nodes, 'g')].sort()).toEqual(['deep', 'inner', 't1', 't2'])
})
it('is empty for a group with no children', () => {
expect(descendantIds(nodes, 'outside').size).toBe(0)
})
it('terminates on a corrupt parent cycle instead of hanging', () => {
const cyclic = [
{ id: 'a', parentId: 'g' },
{ id: 'b', parentId: 'a' },
{ id: 'g', parentId: 'b' } // g is its own descendant
]
expect([...descendantIds(cyclic, 'g')].sort()).toEqual(['a', 'b', 'g'])
})
})
// The one derivation BOTH teardown paths use — Remove (which also ends the sessions) and the stale
// group's Unbind (which does not). Unbind is the documented recovery path for a worktree deleted
// outside the app, and it used to leave `data.cwd = <dead path>` on the children, persisted to
// project.json: tmux hides it (a warm reattach ignores cwd) until a machine reboot, when the cold
// start spawns into the dead path, pty-manager silently falls back to $HOME, and the dead path
// stays in the project file forever.
describe('displacedByWorktree', () => {
const wt = '/wt/feat'
const nodes = [
{ id: 'g', type: 'group', data: { cwd: wt } },
{ id: 'term', type: 'terminal', parentId: 'g', data: { cwd: wt } },
{ id: 'inner', type: 'group', parentId: 'g', data: { cwd: wt } },
{ id: 'nested', type: 'terminal', parentId: 'inner', data: { cwd: `${wt}/pkg` } },
// In the group, but its cwd was pointed somewhere else by hand — it was never displaced.
{ id: 'elsewhere', type: 'terminal', parentId: 'g', data: { cwd: '/repo' } },
// A sibling directory that merely shares the prefix must not be swept up.
{ id: 'prefix', type: 'terminal', parentId: 'g', data: { cwd: '/wt/feature' } },
{ id: 'nocwd', type: 'terminal', parentId: 'g', data: {} },
{ id: 'sticky', type: 'sticky', parentId: 'g', data: { cwd: wt } },
// Same cwd, but not in the group: not this group's business.
{ id: 'stranger', type: 'terminal', data: { cwd: wt } },
// Editor/diff nodes never get a parentId (they float free on the canvas — see
// createEditorNode/createDiffNode), so group membership can't identify them. Path
// containment is the only signal: editor stores the ABSOLUTE path in `filePath`; diff
// stores the repo root in `cwd` and the file's path RELATIVE to it in `filePath`.
{ id: 'editor-in', type: 'editor', data: { filePath: `${wt}/src/index.ts` } },
{ id: 'editor-out', type: 'editor', data: { filePath: '/repo/src/index.ts' } },
// Shares the prefix but is a sibling directory, not really inside the worktree.
{ id: 'editor-prefix', type: 'editor', data: { filePath: '/wt/feature/index.ts' } },
{ id: 'diff-in', type: 'diff', data: { cwd: wt, filePath: 'src/index.ts' } },
{ id: 'diff-out', type: 'diff', data: { cwd: '/repo', filePath: 'src/index.ts' } },
// File-manager nodes: displaced by PATH wherever they sit (they have no session to disturb),
// so one outside the group counts where a terminal outside it does not.
{ id: 'files-in', type: 'files', parentId: 'g', data: { cwd: `${wt}/src` } },
{ id: 'files-outside-group', type: 'files', data: { cwd: wt } },
{ id: 'files-out', type: 'files', data: { cwd: '/repo' } },
{ id: 'files-prefix', type: 'files', data: { cwd: '/wt/feature' } }
]
it('collects every descendant terminal living in the worktree, nested ones included', () => {
expect([...displacedByWorktree(nodes, 'g', wt)].sort()).toEqual(
['diff-in', 'editor-in', 'files-in', 'files-outside-group', 'nested', 'term'].sort()
)
})
it('leaves nodes outside the group, outside the path, or without a cwd alone', () => {
const got = displacedByWorktree(nodes, 'g', wt)
for (const id of [
'elsewhere',
'prefix',
'nocwd',
'sticky',
'stranger',
'g',
'inner',
'editor-out',
'editor-prefix',
'diff-out',
'files-out',
'files-prefix'
]) {
expect(got.has(id)).toBe(false)
}
})
// A file manager left pointing into a removed worktree shows "Could not read this folder"
// forever AND keeps the dead path in project.json — the same persisted-dead-path failure the
// terminal branch exists to prevent. It has no session, so unlike a terminal it is displaced
// wherever it sits, and it gets its cwd re-pointed rather than an editor's `fileMissing`.
it('collects a file-manager node by path, in the group or not', () => {
const got = displacedByWorktree(nodes, 'g', wt)
expect(got.has('files-in')).toBe(true)
expect(got.has('files-outside-group')).toBe(true)
expect(nodes.find((n) => n.id === 'files-outside-group')?.parentId).toBeUndefined()
})
it('collects an editor/diff node by path even though it has no parentId at all', () => {
// Same as 'editor-in'/'diff-in' above, spelled out: neither carries a parentId, and neither
// is a descendant of 'g' by any group-membership test — only the path says they're displaced.
expect(nodes.find((n) => n.id === 'editor-in')?.parentId).toBeUndefined()
expect(nodes.find((n) => n.id === 'diff-in')?.parentId).toBeUndefined()
const got = displacedByWorktree(nodes, 'g', wt)
expect(got.has('editor-in')).toBe(true)
expect(got.has('diff-in')).toBe(true)
})
it('displaces nothing for an empty worktree path (never sweeps the whole canvas)', () => {
expect(displacedByWorktree(nodes, 'g', '').size).toBe(0)
})
})
describe('isInsideDir', () => {
it('matches the directory itself and anything under it', () => {
expect(isInsideDir('/wt/feat', '/wt/feat')).toBe(true)
expect(isInsideDir('/wt/feat/src', '/wt/feat')).toBe(true)
expect(isInsideDir('/wt/feat/', '/wt/feat')).toBe(true)
})
it('does not match a sibling that merely shares a prefix', () => {
expect(isInsideDir('/wt/feature', '/wt/feat')).toBe(false)
})
it('is false for an unset cwd (nothing to displace)', () => {
expect(isInsideDir(undefined, '/wt/feat')).toBe(false)
expect(isInsideDir('', '/wt/feat')).toBe(false)
})
})
describe('worktreeRemoveMessage', () => {
const base = { branch: 'feat/x', path: '/wt/feat-x', canDelete: true, deleteFromDisk: true }
it('names the branch and the directory that will be destroyed', () => {
const msg = worktreeRemoveMessage(base)
expect(msg).toContain('Branch: feat/x')
expect(msg).toContain('Directory: /wt/feat-x')
})
it('attributes an agent-opened removal (it used to be identical to a user-initiated one)', () => {
expect(worktreeRemoveMessage({ ...base, requestedBy: 'claude-1' })).toContain(
'Agent "claude-1" wants to remove this worktree.'
)
// A user-initiated removal claims no agent.
expect(worktreeRemoveMessage(base)).not.toContain('Agent "')
})
it('an adopted worktree defaults to unbind, and says so; the disk opt-in is spelled out', () => {
const adopted = { ...base, canDelete: false, deleteFromDisk: false }
const unbind = worktreeRemoveMessage(adopted)
expect(unbind).toContain('not created by nodeterm')
expect(unbind).not.toContain('DELETED')
expect(worktreeRemoveMessage({ ...adopted, deleteFromDisk: true })).toContain(
'⚠ The worktree directory will be DELETED. Its branch is kept.'
)
})
it('carries the uncommitted-work warning', () => {
expect(worktreeRemoveMessage({ ...base, warning: '3 uncommitted file(s) in the worktree.' })).toContain(
'⚠ 3 uncommitted file(s) in the worktree.'
)
})
})
describe('filterWorktrees', () => {
const entries = [
entry('/repo.worktrees/feature-login', 'feature/login'),
entry('/repo.worktrees/fix-api', 'fix/API'),
entry('/repo.worktrees/detached', null)
]
it('matches branch or path without case sensitivity', () => {
expect(filterWorktrees(entries, 'LOGIN')).toEqual([entries[0]])
expect(filterWorktrees(entries, 'fix api')).toEqual([entries[1]])
})
it('returns every entry for a blank query and none for a miss', () => {
expect(filterWorktrees(entries, ' ')).toBe(entries)
expect(filterWorktrees(entries, 'not-here')).toEqual([])
})
})
// Pure worktree-creation resolver: what baseRef and path TEMPLATE a new worktree should default to,
// given a project's own settings. Neither function does IO or validates a path — computeWorktreePath
// (the caller) already refuses a shallow-rooted result, so a hostile basePath is left to fall back
// exactly as it does today; see the `computeWorktreePath` case below.
describe('effectiveWorktreeBaseRef', () => {
const entries = [entry('/repo', 'trunk'), entry('/wt/x', 'feature/x')]
it('a project baseRef wins over the repo-derived default', () => {
const project: ProjectWorktreeDefaults = { baseRef: 'release' }
expect(effectiveWorktreeBaseRef(project, entries)).toBe('release')
})
it('falls back to resolveBaseRef(entries) when the project has no baseRef', () => {
expect(effectiveWorktreeBaseRef(undefined, entries)).toBe('trunk')
expect(effectiveWorktreeBaseRef({}, entries)).toBe('trunk')
})
it('treats a whitespace-only project baseRef as unset', () => {
expect(effectiveWorktreeBaseRef({ baseRef: ' ' }, entries)).toBe('trunk')
})
it('falls all the way to DEFAULT_BASE_REF when neither the project nor the repo says', () => {
expect(effectiveWorktreeBaseRef(undefined, [])).toBe(DEFAULT_BASE_REF)
})
})
describe('effectiveWorktreeTemplate', () => {
it('a set project basePath becomes `<basePath>/${branch}`', () => {
expect(effectiveWorktreeTemplate({ basePath: '/srv/worktrees' }, undefined)).toBe(
'/srv/worktrees/${branch}'
)
})
it('joins with exactly one slash even when basePath has a trailing slash', () => {
expect(effectiveWorktreeTemplate({ basePath: '/srv/worktrees/' }, undefined)).toBe(
'/srv/worktrees/${branch}'
)
})
it('a whitespace-only basePath is ignored, falling through to the global template', () => {
expect(effectiveWorktreeTemplate({ basePath: ' ' }, './worktrees')).toBe('./worktrees')
})
it('falls back to the trimmed global template when there is no project basePath', () => {
expect(effectiveWorktreeTemplate(undefined, ' ./worktrees ')).toBe('./worktrees')
expect(effectiveWorktreeTemplate({}, './worktrees')).toBe('./worktrees')
})
it('falls back to DEFAULT_WORKTREE_PATH_TEMPLATE when neither project basePath nor global template is set', () => {
expect(effectiveWorktreeTemplate(undefined, undefined)).toBe(DEFAULT_WORKTREE_PATH_TEMPLATE)
expect(effectiveWorktreeTemplate({}, ' ')).toBe(DEFAULT_WORKTREE_PATH_TEMPLATE)
})
// The function itself does no path resolution or validation — it only builds a template string.
// A hostile basePath like '/' must still end up refused, but that refusal happens DOWNSTREAM in
// computeWorktreePath (via resolvePathFromRepo's shallow-root guard), not here. Prove the chain
// actually holds by feeding the synthesized template through computeWorktreePath.
it('a rooted basePath produces a template that computeWorktreePath later refuses', () => {
const template = effectiveWorktreeTemplate({ basePath: '/' }, undefined)
expect(template).toBe('/${branch}')
expect(computeWorktreePath('/src/repo', 'topic/a', template)).toBe('')
})
})
describe('resolveWorktreeBase (issue #530 — --base <ref|stationId>)', () => {
// A wave-one worktree frame (g1, branch wave1) holding an agent node (a1), a nested inner
// frame (g1a) holding a2; a loose node (n0); an unbound frame (g2) with a member (b1).
const NODES: WorktreeBaseNode[] = [
{ id: 'g1', worktree: { branch: 'wave1' } },
{ id: 'a1', parentId: 'g1' },
{ id: 'g1a', parentId: 'g1' },
{ id: 'a2', parentId: 'g1a' },
{ id: 'n0' },
{ id: 'g2' },
{ id: 'b1', parentId: 'g2' }
]
it('no --base means the default', () => {
expect(resolveWorktreeBase(undefined, 'wave2', NODES)).toEqual({ kind: 'default' })
expect(resolveWorktreeBase(' ', 'wave2', NODES)).toEqual({ kind: 'default' })
})
it('a member node resolves through its bound group to the branch', () => {
expect(resolveWorktreeBase('a1', 'wave2', NODES)).toEqual({
kind: 'station',
ref: 'wave1',
stationId: 'a1',
groupId: 'g1'
})
})
it('a node in a NESTED frame climbs to the nearest bound ancestor', () => {
expect(resolveWorktreeBase('a2', 'wave2', NODES)).toEqual({
kind: 'station',
ref: 'wave1',
stationId: 'a2',
groupId: 'g1'
})
})
it('the bound group id itself is a station', () => {
expect(resolveWorktreeBase('g1', 'wave2', NODES)).toEqual({
kind: 'station',
ref: 'wave1',
stationId: 'g1',
groupId: 'g1'
})
})
it('a node outside any worktree frame is an explicit refusal — never reinterpreted as a ref', () => {
for (const id of ['n0', 'b1', 'g2']) {
const r = resolveWorktreeBase(id, 'wave2', NODES)
expect(r.kind).toBe('error')
if (r.kind === 'error') expect(r.error).toContain('not inside a worktree-bound frame')
}
})
it('a station whose branch IS the new branch is refused (self-base)', () => {
const r = resolveWorktreeBase('a1', 'wave1', NODES)
expect(r.kind).toBe('error')
if (r.kind === 'error') expect(r.error).toContain('based on itself')
})
it('a plain ref self-base is refused too', () => {
const r = resolveWorktreeBase('wave2', 'wave2', NODES)
expect(r.kind).toBe('error')
if (r.kind === 'error') expect(r.error).toContain('based on itself')
})
it('a value naming no node passes through as a validated git ref', () => {
expect(resolveWorktreeBase('main', 'wave2', NODES)).toEqual({ kind: 'ref', ref: 'main' })
expect(resolveWorktreeBase('origin/main', 'wave2', NODES)).toEqual({
kind: 'ref',
ref: 'origin/main'
})
})
it('a value that is neither a node nor a valid ref is refused', () => {
for (const bad of ['-rf', 'a..b', 'has space']) {
const r = resolveWorktreeBase(bad, 'wave2', NODES)
expect(r.kind).toBe('error')
if (r.kind === 'error') expect(r.error).toContain('neither')
}
})
it('a forged parentId cycle terminates as a refusal instead of hanging', () => {
// project.json is hand-editable and git-shared; the walk is visited-set guarded.
const cyc: WorktreeBaseNode[] = [
{ id: 'x', parentId: 'y' },
{ id: 'y', parentId: 'x' }
]
const r = resolveWorktreeBase('x', 'wave2', cyc)
expect(r.kind).toBe('error')
})
})