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
export interface GroupWorktree {
/** Main repo root chosen at bind time. */
repoPath: string
/** The worktree's branch (new or existing). */
branch: string
/** Branch this was created from — the merge target (e.g. "main"). */
baseRef: string
/** Worktree directory on disk. */
path: string
/** Whether this app created the worktree (gates safe directory deletion). */
createdByApp: boolean
}
/** One entry's outcome from materializing a project's `sharedPaths` into a worktree
* (core/worktree-shared-paths.ts). Lives here in `shared` so the renderer's `WorktreeApi` type can
* name it without importing core; core's module re-exports it for its own callers/tests. */
export interface SharedPathResult {
path: string
status:
| 'linked'
| 'skipped-missing-source'
| 'skipped-exists'
| 'skipped-reserved'
| 'skipped-unsafe'
| 'error'
/** Present only for `error` (or a noteworthy skip): a short human-readable reason. */
note?: string
}
export interface WorktreeEntry {
path: string
branch: string | null
head: string | null
isBare: boolean
/**
* git still LISTS a worktree whose directory was deleted behind its back — it just tags it
* `prunable` (until someone runs `git worktree prune`). Treating such an entry as alive is what
* makes a dead binding look healthy, so the flag has to survive the parse.
*/
prunable?: boolean
}
/** `git worktree list`, plus WHETHER GIT COULD BE READ AT ALL — see `worktree-ops.listWorktrees`. */
export interface WorktreeListResult {
ok: boolean
entries: WorktreeEntry[]
}
/** The node fields that can say "this session does not run on this machine". */
interface RemoteNodeLike {
/** SSH-PROJECT terminal (`createTerminalNode(..., project.ssh)`) — the connection it runs on. */
ssh?: unknown
/** SSH-PROJECT terminal: its tmux server lives on the host, not here. */
sshRemoteTmux?: unknown
}
/**
* Does this node's session live on a REMOTE host?
*
* Worktrees are local-only in v1: `git worktree` runs against the project's local filesystem. A
* node whose tmux session is on another machine must therefore never be moved into one — its
* session would be destroyed and respawned into a directory that does not exist there, and the dead
* path would be persisted to `project.json`.
*
* An SSH-PROJECT terminal carries BOTH `data.ssh` (the connection it runs on) and
* `data.sshRemoteTmux` (its tmux server lives on the host), and guarding only one is how the exact
* node this protects slipped through — so ask about both.
*/
export function isRemoteSessionNode(data: RemoteNodeLike | undefined): boolean {
return !!(data && (data.ssh || data.sshRemoteTmux))
}
/**
* Reject refs that could smuggle CLI flags (leading `-`) or are not valid git refs.
* Electron-free port of git-service.ts's `isValidRef` so worktree-ops can validate too.
*/
export function isValidGitRef(name: string): boolean {
const n = name.trim()
if (!n || n.startsWith('-')) return false
return !/[\s~^:?*[\\]|\.\.|^\/|\/$|@\{/.test(n)
}
/** The node shape `resolveWorktreeBase` walks — id, containment, and (for groups) the binding. */
export interface WorktreeBaseNode {
id: string
parentId?: string
/** The group's binding, when this node is a worktree-bound group frame. */
worktree?: Pick<GroupWorktree, 'branch'>
}
export type WorktreeBaseResolution =
/** No `--base` given — the caller falls back to its default base. */
| { kind: 'default' }
/** A plain git ref, validated by `isValidGitRef`. */
| { kind: 'ref'; ref: string }
/** A STATION: the id named a node/group on the canvas, and the base is the branch of the
* worktree-bound group that contains it (or is it). */
| { kind: 'station'; ref: string; stationId: string; groupId: string }
| { kind: 'error'; error: string }
/**
* Resolve `open-worktree --base <value>` (issue #530): the value may be a git ref, OR the id of a
* station — a node or group frame inside a worktree-bound group — in which case the base is that
* station's branch, resolved through the binding. This lets an orchestrator say "branch off what
* that station is working on" by IDENTITY, instead of restating the branch name (and getting it
* wrong) in every downstream call.
*
* Precedence: an id that names an EXISTING node is always read as a station — a node that is not
* inside a worktree frame is an explicit refusal, never silently reinterpreted as a git ref (an
* id that matched a node was clearly meant as one; falling through would base the worktree on a
* ref that happens to parse). A value naming no node must be a valid git ref. Refusals are
* explicit for: a station with no binding, a base that resolves to the branch being created
* (a worktree cannot be based on itself), and a value that is neither a node nor a valid ref.
*
* Note the timing this deliberately does NOT change: the base is captured when the worktree is
* CREATED, exactly like a plain ref — deferred (create-at-fire) worktrees are a separate design
* (the rest of issue #530). The docs tell the orchestrator to create a downstream worktree after
* the upstream station has committed.
*/
export function resolveWorktreeBase(
baseArg: string | undefined,
newBranch: string,
nodes: WorktreeBaseNode[]
): WorktreeBaseResolution {
const raw = (baseArg ?? '').trim()
if (!raw) return { kind: 'default' }
const byId = new Map(nodes.map((n) => [n.id, n]))
const station = byId.get(raw)
if (station) {
// Climb from the station to the nearest worktree-bound group (the station may BE the group).
// Visited-set guarded: parentId chains come from a hand-editable, git-shared project.json,
// and a forged cycle must not hang the verb.
const seen = new Set<string>()
let cur: WorktreeBaseNode | undefined = station
while (cur && !seen.has(cur.id)) {
seen.add(cur.id)
const branch = cur.worktree?.branch
if (branch) {
if (branch === newBranch) {
return {
kind: 'error',
error: `--base ${raw} resolves to branch "${branch}", which is the branch being created — a worktree cannot be based on itself`
}
}
return { kind: 'station', ref: branch, stationId: raw, groupId: cur.id }
}
cur = cur.parentId ? byId.get(cur.parentId) : undefined
}
return {
kind: 'error',
error: `--base ${raw} names a node that is not inside a worktree-bound frame — pass a git ref, or a station (node or group id) inside a worktree frame`
}
}
if (!isValidGitRef(raw)) {
return {
kind: 'error',
error: `--base "${raw}" is neither an existing node/group id nor a valid git ref`
}
}
if (raw === newBranch) {
return { kind: 'error', error: `--base "${raw}" is the branch being created — a worktree cannot be based on itself` }
}
return { kind: 'ref', ref: raw }
}
/** Flatten a branch name into a filesystem-safe, flag-safe slug. */
export function sanitizeWorktreeBranch(input: string): string {
return input
.trim()
.toLowerCase()
.replace(/[^a-z0-9/_-]+/g, '-') // illegal chars -> dash
.replace(/^[-/]+/, '') // no leading dash (flag injection) or slash
.replace(/-+/g, '-')
.replace(/(^-|-$)/g, '')
}
/**
* Global template for new worktrees. It deliberately lives NEXT TO the checkout instead of under
* app data: the location is predictable from a shell/file picker, while keeping other worktrees
* outside the main checkout avoids nested-repository tooling surprises.
*/
export const DEFAULT_WORKTREE_PATH_TEMPLATE = '../${repoName}.worktrees/${branch}'
const WORKTREE_TEMPLATE_TOKEN =
/\$\{(repoName|reponame|defaultFolderName|branch)\}|\$(repoName|reponame|defaultFolderName|branch)\b/g
const WORKTREE_BRANCH_TOKEN = /\$\{branch\}|\$branch\b/
/** Browser-safe lexical path resolution (this shared module is bundled into the renderer). */
function resolvePathFromRepo(repoRoot: string, configuredPath: string): string {
const root = repoRoot.trim().replace(/\\/g, '/').replace(/\/+$/, '')
const configured = configuredPath.trim().replace(/\\/g, '/')
if (!root || !configured) return ''
const absolute = configured.startsWith('/') || /^[a-zA-Z]:\//.test(configured)
const combined = absolute ? configured : `${root}/${configured}`
const drive = combined.match(/^([a-zA-Z]:)\//)?.[1] ?? ''
const rooted = combined.startsWith('/') || !!drive
const body = drive ? combined.slice(drive.length + 1) : combined.replace(/^\/+/, '')
const parts: string[] = []
for (const part of body.split('/')) {
if (!part || part === '.') continue
if (part === '..') {
if (parts.length) parts.pop()
else if (!rooted) parts.push(part)
continue
}
parts.push(part)
}
// Refuse a result that lands at (or directly under) the filesystem root. A pathological template
// such as `../../../../..` climbs past the repo and clamps at `/`, yielding `/branch-x`; the
// Server Edition often runs as root and `git worktree add /branch-x` would cheerfully create that
// at the filesystem root. The original template code guarded this explicitly (see the historical
// computeWorktreePath comment); the rewrite dropped it. A rooted path needs at least two segments
// (e.g. `/srv/worktrees` is fine, `/worktrees` is not) — a Windows drive root is refused the same
// way. Callers already treat '' as "no default / no writable base".
if ((rooted || drive) && parts.length < 2) return ''
const prefix = drive ? `${drive}/` : rooted ? '/' : ''
return `${prefix}${parts.join('/')}`
}
/**
* Expand a worktree path template relative to the repository root.
*
* Supported spellings intentionally include both `$name` and `${name}`. `$repoName`, the
* lower-case `$reponame` spelling, and `$defaultFolderName` all mean the main checkout's folder
* name; the latter is an explicit human-readable alias for users who think of that checkout as the
* "default worktree". `$branch` is the filesystem-safe branch slug. When the template omits a
* branch token, the slug is appended automatically, so concise bases such as `./worktrees` and
* `../$reponame.worktrees` remain collision-safe.
*/
export function computeWorktreePath(
repoRoot: string,
branch: string,
template = DEFAULT_WORKTREE_PATH_TEMPLATE
): string {
const root = repoRoot.trim().replace(/[\\/]+$/, '')
const repoName = root.split(/[\\/]/).pop() || ''
const flatBranch = sanitizeWorktreeBranch(branch).replace(/\//g, '-')
if (!root || !repoName || !flatBranch) return ''
const source = template.trim() || DEFAULT_WORKTREE_PATH_TEMPLATE
const hasBranchToken = WORKTREE_BRANCH_TOKEN.test(source)
const expanded = source.replace(WORKTREE_TEMPLATE_TOKEN, (_match, braced, plain) => {
const token = braced || plain
return token === 'branch' ? flatBranch : repoName
})
const withBranch = hasBranchToken ? expanded : `${expanded.replace(/\/+$/, '')}/${flatBranch}`
return resolvePathFromRepo(root, withBranch)
}
/**
* Resolve the on-disk worktree directory for a create: an explicit `--path` wins; otherwise the
* configured template relative to that session's repository root. A remote/relay tab therefore
* still resolves on the host filesystem: its `repoRoot` comes from the same session core that runs
* the git operation. Kept async for its existing callers/API even though template expansion itself
* is synchronous.
*/
export async function resolveWorktreePath(args: {
explicitPath?: string
repoRoot: string
branch: string
template?: string
}): Promise<string> {
const explicit = args.explicitPath?.trim()
if (explicit) return explicit
return computeWorktreePath(args.repoRoot, args.branch, args.template)
}
/** Values the worktree dialog collects. Mapped to a `GroupWorktree` by `worktreeFromCreate`. */
export interface WorktreeCreateValue {
repoPath: string
mode: 'new' | 'existing'
branch: string
baseRef: string
path: string
}
/** Last-resort merge target when the repo's default branch cannot be read. */
export const DEFAULT_BASE_REF = 'main'
/**
* The repo's default branch = the branch of its MAIN checkout, which git prints FIRST in
* `git worktree list` (the caller must keep git's order). Hardcoding 'main' would send a
* master/trunk repo's merge at a ref that does not exist.
*/
export function resolveBaseRef(entries: WorktreeEntry[]): string {
return entries[0]?.branch?.trim() || DEFAULT_BASE_REF
}
/** The worktree-related fields a project can override — see `effectiveWorktreeBaseRef` /
* `effectiveWorktreeTemplate`. Both optional: an unset or whitespace-only value defers below it. */
export interface ProjectWorktreeDefaults {
basePath?: string
baseRef?: string
}
/**
* The baseRef a NEW worktree should default to: a project override wins, else the repo's own
* default branch (`resolveBaseRef`, which falls back to `DEFAULT_BASE_REF`). Pure — no IO.
*/
export function effectiveWorktreeBaseRef(
project: ProjectWorktreeDefaults | undefined,
entries: WorktreeEntry[]
): string {
return project?.baseRef?.trim() || resolveBaseRef(entries)
}
/**
* The path TEMPLATE a new worktree's location should expand from — fed straight into
* `computeWorktreePath`. A project `basePath` becomes `<basePath>/${branch}` (exactly one slash
* between the two); otherwise the given global template, or `DEFAULT_WORKTREE_PATH_TEMPLATE`.
*
* Deliberately does NOT resolve or validate `basePath` — `computeWorktreePath`'s
* `resolvePathFromRepo` already refuses a template that resolves to (or under) the filesystem root,
* so a hostile `basePath` such as `'/'` synthesizes `/${branch}`, which that downstream guard
* refuses (returns `''`), and creation falls back exactly as it does today. Pure — no IO.
*/
export function effectiveWorktreeTemplate(
project: ProjectWorktreeDefaults | undefined,
globalTemplate: string | undefined
): string {
const basePath = project?.basePath?.trim()
if (basePath) return `${basePath.replace(/\/+$/, '')}/\${branch}`
return globalTemplate?.trim() || DEFAULT_WORKTREE_PATH_TEMPLATE
}
/**
* Binding for a worktree THIS APP just created — `createdByApp: true` grants Remove the right
* to delete the directory. Only call this after `git worktree add` succeeded.
*/
export function worktreeFromCreate(v: WorktreeCreateValue): GroupWorktree {
return {
repoPath: v.repoPath.trim(),
branch: v.branch.trim(),
baseRef: v.baseRef.trim() || DEFAULT_BASE_REF,
// A Windows path is stored '/'-separated (case kept), the shape `git worktree list` prints, so
// the binding and git agree without a key fold. A POSIX path is untouched — a backslash is a
// legal filename character there, not a separator.
path: isWindowsShapedPath(v.path.trim()) ? v.path.trim().replace(/\\/g, '/') : v.path.trim(),
createdByApp: true
}
}
/**
* Binding for a worktree that ALREADY EXISTED on disk (adopted from `git worktree list`) —
* `createdByApp: false`, so Remove must never delete a directory the user made themselves.
* Returns null when the binding cannot be trusted (detached HEAD, unknown repo root/path).
*/
export function worktreeFromEntry(
entry: WorktreeEntry,
repoPath: string,
baseRef: string
): GroupWorktree | null {
const path = entry.path.trim()
const branch = entry.branch?.trim()
const repo = repoPath.trim()
if (!repo || !branch || !path) return null
return {
repoPath: repo,
branch,
baseRef: baseRef.trim() || DEFAULT_BASE_REF,
path,
createdByApp: false
}
}
/** Parse `git worktree list --porcelain` into structured entries. */
export function parseWorktreePorcelain(out: string): WorktreeEntry[] {
const entries: WorktreeEntry[] = []
let cur: Partial<WorktreeEntry> | null = null
const flush = (c: Partial<WorktreeEntry>): void => {
entries.push({
path: c.path!,
branch: c.branch ?? null,
head: c.head ?? null,
isBare: c.isBare ?? false,
prunable: c.prunable ?? false
})
}
for (const raw of out.split('\n')) {
const line = raw.trimEnd()
if (line.startsWith('worktree ')) {
if (cur) flush(cur)
cur = { path: line.slice('worktree '.length), isBare: false }
} else if (!cur) {
continue
} else if (line.startsWith('HEAD ')) {
cur.head = line.slice('HEAD '.length)
} else if (line.startsWith('branch ')) {
cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '')
} else if (line === 'bare') {
cur.isBare = true
} else if (line === 'prunable' || line.startsWith('prunable ')) {
// e.g. "prunable gitdir file points to non-existent location" — the directory is gone.
cur.prunable = true
}
}
if (cur) flush(cur)
return entries
}
/**
* The identity key of a worktree/repo path, for COMPARING paths — never for using one. Git prints
* `C:/r/wt` on Windows while a typed or pasted binding says `C:\r\wt` (or `c:/…`), and NTFS is
* case-insensitive by default, so a Windows-shaped path (a drive letter or UNC — see
* `isWindowsShapedPath`) is folded to forward slashes and lower case. A POSIX path keeps its exact
* case and is only stripped of trailing slashes — byte-identical to the comparison this replaced. Keyed on the
* path's SHAPE, not on `process.platform`: this module runs in the renderer, whose platform is not
* the core's.
*/
export function worktreePathKey(p: string): string {
return pathKey(p.trim())
}
/** An absolute Windows path: a drive letter (`C:`) or UNC (`\\server`, or `//server` as git prints
* it). Shape, not a stray backslash: on POSIX `\\` is a legal filename character, and folding such
* a path's case would make two distinct POSIX directories compare equal. */
export function isWindowsShapedPath(t: string): boolean {
return /^[A-Za-z]:|^[\\/]{2}/.test(t)
}
/** `worktreePathKey` without the trim — `isAncestorPath` and the removal guard never trimmed. */
function pathKey(t: string): string {
if (!isWindowsShapedPath(t)) return t.replace(/\/+$/, '')
return t.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
}
/** Is `child` the directory `parent` itself, or somewhere inside it? (Trailing slashes ignored;
* Windows-shaped paths compared by `worktreePathKey`.) */
export const isAncestorPath = (parent: string, child: string): boolean => {
const p = pathKey(parent)
const c = pathKey(child)
return c === p || c.startsWith(p + '/')
}
/** `isAncestorPath` for an optional cwd: "does this node live in that directory?" */
export const isInsideDir = (cwd: string | undefined, dir: string): boolean =>
!!cwd && !!dir && isAncestorPath(dir, cwd)
/**
* Every node under `rootId` — children, grandchildren, … — not just the direct children.
*
* Worktree teardown has to reach ALL of them: a terminal inside a nested group is living in the
* worktree directory just as much as a direct child, and a removal that only walked one level left
* it holding a session (and a cwd) in a directory that no longer exists.
*/
export function descendantIds(
nodes: readonly { id: string; parentId?: string }[],
rootId: string
): Set<string> {
const byParent = new Map<string, string[]>()
for (const n of nodes) {
if (!n.parentId) continue
const siblings = byParent.get(n.parentId) ?? []
siblings.push(n.id)
byParent.set(n.parentId, siblings)
}
const out = new Set<string>()
const stack = [...(byParent.get(rootId) ?? [])]
while (stack.length) {
const id = stack.pop() as string
if (out.has(id)) continue // cycle guard: a corrupt parentId chain must not hang the app
out.add(id)
stack.push(...(byParent.get(id) ?? []))
}
return out
}
/** The shape `displacedByWorktree` needs of a canvas node (structural, so the shared layer stays
* free of React Flow types). */
interface WorktreeNodeLike {
id: string
type?: string
parentId?: string
data?: { cwd?: unknown; filePath?: unknown }
}
/**
* The nodes a worktree teardown DISPLACES: every descendant of the bound group that carries a
* working directory (a terminal or a chat) inside the worktree path, PLUS any editor/diff node
* anywhere on the canvas whose file lives inside it, PLUS any file-manager node anywhere whose
* directory is inside it (see the `files` branch for why its rule is the editor one, not the
* terminal one).
*
* BOTH teardown paths derive from this — Remove (which also ends their sessions and respawns them)
* and a stale group's Unbind (which touches no process at all). Unbind is the documented recovery
* path for a worktree deleted outside the app — the only action a stale group offers — and leaving
* `data.cwd` on the dead path there is not cosmetic: it is persisted to `project.json`, tmux hides
* it (a warm reattach ignores cwd), and the next machine reboot cold-starts the terminal into a
* directory that no longer exists, where pty-manager silently falls back to $HOME while the dead
* path stays in the project file forever.
*
* Nodes whose cwd was never inside the worktree (pointed elsewhere by hand, a sibling directory
* that merely shares the prefix, no cwd at all) are NOT displaced — they were never affected, and
* rewriting them would be a change the user never asked for.
*
* Terminal displacement is GROUP-scoped (`under.has`) because a cwd match alone is too broad —
* plenty of terminals legitimately share a cwd with a worktree without living inside its frame.
* Editor/diff nodes get no such scoping: `createEditorNode`/`createDiffNode` never set a
* `parentId` (they float free on the canvas, `group: null`), so they are never a "descendant" of
* anything — path containment is the only signal there is. A node that opened a file out of a
* worktree is displaced by that worktree going away no matter where it happens to sit visually.
* Editor stores the file's ABSOLUTE path in `filePath`; diff stores the repo root in `cwd` and the
* file's path RELATIVE to it in `filePath`, so the two are joined before the containment check.
*/
export function displacedByWorktree(
nodes: readonly WorktreeNodeLike[],
groupId: string,
worktreePath: string
): Set<string> {
if (!worktreePath) return new Set()
const under = descendantIds(nodes, groupId)
const out = new Set<string>()
for (const n of nodes) {
if (n.type === 'terminal') {
if (!under.has(n.id)) continue
const cwd = typeof n.data?.cwd === 'string' ? n.data.cwd : undefined
if (isInsideDir(cwd, worktreePath)) out.add(n.id)
} else if (n.type === 'files') {
// Checked ANYWHERE on the canvas, like editor/diff and unlike terminal — the `under`
// restriction on terminals is there because displacing one RESPAWNS it, and a session the
// user rooted here by hand should not be restarted from under them. A file manager has no
// session: the directory it is showing is simply gone, wherever the node happens to sit, and
// resetting its cwd costs the user nothing. Left alone it would show "Could not read this
// folder" forever AND keep the dead path in project.json, which is the same persisted-dead-
// path failure the terminal branch above exists to prevent.
//
// It gets `cwd` reset rather than `fileMissing`: a directory CAN be re-pointed at the
// fallback, which is exactly why editor/diff get the flag instead — there is nothing
// sensible to re-point a dead FILE at.
const cwd = typeof n.data?.cwd === 'string' ? n.data.cwd : undefined
if (isInsideDir(cwd, worktreePath)) out.add(n.id)
} else if (n.type === 'editor' || n.type === 'diff') {
const filePath = typeof n.data?.filePath === 'string' ? n.data.filePath : undefined
const cwd = typeof n.data?.cwd === 'string' ? n.data.cwd : undefined
const abs = n.type === 'diff' && cwd && filePath ? `${cwd}/${filePath}` : filePath
if (isInsideDir(abs, worktreePath)) out.add(n.id)
}
}
return out
}
/** Refuse removals that would nuke the repo, home, or filesystem root. */
export function isDangerousWorktreeRemovalPath(worktreePath: string, repoPath: string, homeDir: string): boolean {
const wt = pathKey(worktreePath || '')
if (!wt) return true
// A bare drive root (`C:`, `C:\`, `c:/`) is Windows' `/`.
if (wt === '/' || /^[a-z]:$/.test(wt)) return true
if (wt === pathKey(repoPath) || wt === pathKey(homeDir)) return true
// worktree is an ancestor of the repo or of home → dangerous.
if (isAncestorPath(wt, repoPath) || isAncestorPath(wt, homeDir)) return true
return false
}
/** Choose how to land a branch onto its base without corrupting a live checkout. */
export function decideMergeStrategy(args: { baseCheckedOutPath: string | null; baseDirty: boolean }):
| { kind: 'fetch-update' }
| { kind: 'merge-in-place'; path: string }
| { kind: 'blocked'; reason: string } {
if (args.baseCheckedOutPath === null) return { kind: 'fetch-update' }
if (args.baseDirty) {
return { kind: 'blocked', reason: 'The base branch checkout has uncommitted changes. Commit or stash them first.' }
}
return { kind: 'merge-in-place', path: args.baseCheckedOutPath }
}
/** What the removal confirm needs to say — WHO asked, and WHAT exactly gets destroyed. */
export interface WorktreeRemovePrompt {
branch: string
path: string
/** nodeterm created the directory → deleting it is the action; otherwise Unbind is the default. */
canDelete: boolean
/** The live value of the "delete from disk too" box (for an adopted worktree). */
deleteFromDisk: boolean
/** e.g. "3 uncommitted file(s) in the worktree." */
warning?: string
/** Title of the AGENT that asked for this. Absent = the user asked for it themselves. */
requestedBy?: string
}
/**
* The removal dialog's text. Pure, so it can be read (and tested) without the canvas.
*
* Two things it must never omit again:
* - ATTRIBUTION. An agent can open this dialog (canvas-control `close-worktree --mode remove`).
* The old text was byte-identical to a user-initiated removal, so a user who never asked for it
* had no way to tell where it came from — while `write`/`close` have always said
* `Agent "<title>" wants to …`.
* - THE TARGET. It named neither the branch nor the directory, so an agent could open it for one
* worktree and the user could approve the deletion of a worktree they never looked at.
*/
export function worktreeRemoveMessage(p: WorktreeRemovePrompt): string {
const who = p.requestedBy
? `Agent "${p.requestedBy}" wants to remove this worktree.\n\n`
: ''
const what = `Branch: ${p.branch}\nDirectory: ${p.path}\n\n`
const body = p.canDelete
? // Promise only what we will actually do. `git branch -d` REFUSES an unmerged branch (and we
// never escalate to -D), so "its branch is deleted" was a promise the op could not keep.
'Remove this worktree? Its directory is deleted, and its branch too — unless the branch ' +
'still has unmerged commits, in which case it is kept.'
: 'This worktree was not created by nodeterm.\n\nUnbind detaches this group and leaves the ' +
'worktree untouched on disk.'
const optIn =
p.deleteFromDisk && !p.canDelete
? '\n\n⚠ The worktree directory will be DELETED. Its branch is kept.'
: ''
const warn = p.warning ? `\n\n⚠ ${p.warning}` : ''
return `${who}${what}${body}${optIn}${warn}`
}
/** Case-insensitive branch/path search for the existing-worktree picker. Every term must match. */
export function filterWorktrees(entries: WorktreeEntry[], query: string): WorktreeEntry[] {
const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean)
if (!terms.length) return entries
return entries.filter((entry) => {
const haystack = `${entry.branch ?? ''}\n${entry.path}`.toLowerCase()
return terms.every((term) => haystack.includes(term))
})
}