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
/**
* The decisions a file-manager node makes, kept pure so they can be pressed in a test rather than
* clicked in the app: which directory "up" is, what the breadcrumb shows, what a filter matches,
* and what happens when you open a thing.
*
* Paths are `/`-separated absolutes throughout, remote ones included — the node talks to an
* `FsApi`, which is the same shape for the local filesystem, an SSH project's host over the
* ControlMaster, and a relay peer's core.
*
* **Windows is a known, INHERITED gap.** Every split here is on `/` alone, so `C:\\x\\y` reads as a
* single segment: one breadcrumb, and `folderTitle` returning the whole path. This is shared with
* `lib/explorerCreate.ts` (`parentDir`, `newEntryPath`, `ancestorDirs`), which the Explorer drawer
* and the canvas "New file…" already run on, so a files node is not the thing that introduces it —
* but Windows is being brought up as a first-class desktop target, and `quality-windows` now runs
* on this branch. When it is closed, close it in ONE place for both: the path dialect belongs to
* the filesystem-owning CORE, not the viewer, which is the rule `terminal/file-links.ts` already
* implements and the one to copy.
*/
import { isMediaFile } from '../state/workspace'
import { opensInEditor } from './openTarget'
import { folderTitle } from './explorerCreate'
import { isDownloadablePath, type DownloadRoute } from './download'
export { folderTitle, parentDir } from './explorerCreate'
/** One breadcrumb: what to show, and where clicking it goes. */
export interface Crumb {
name: string
path: string
}
/**
* A node header is a few hundred pixels wide and a real project path is not. `max` is the number
* of TRAILING segments kept; anything deeper is collapsed into a single leading crumb that still
* navigates (to the last dropped directory), because a breadcrumb you cannot click is just text.
* Root is always reachable as the first crumb for the same reason.
*/
export function breadcrumbs(path: string, max = 3): Crumb[] {
const segs = path.split('/').filter(Boolean)
// The crumbs keep the path's OWN root rather than inventing `/`. An SSH project's `remoteCwd`
// defaults to `~` (SshSection), so a remote files node routinely stands on `~/a/b`; prefixing
// every crumb with `/` turned the `a` crumb into the literal `/~/a`, which exists on no host —
// the listing came back empty, so did its parent `/~`, and the node reported "Could not reach
// this folder." for a directory it had been showing a second earlier. A relative path has no
// root crumb: its first segment (`~`) IS the top the user can climb to from here.
const absolute = path.startsWith('/')
const all: Crumb[] = absolute ? [{ name: '/', path: '/' }] : []
let acc = ''
for (const s of segs) {
acc = (acc || absolute) ? `${acc}/${s}` : s // first relative segment carries no separator
all.push({ name: s, path: acc })
}
if (all.length <= max + 1) return all
// Keep the first crumb (root, or the relative top), then an ellipsis crumb that navigates to
// the deepest hidden directory, then the tail. `max + 1` accounts for that first crumb, which is
// never dropped.
const hidden = all.slice(1, all.length - max)
const ellipsis: Crumb = { name: '…', path: hidden[hidden.length - 1].path }
return [all[0], ellipsis, ...all.slice(all.length - max)]
}
/**
* How a files node is re-pointed when the worktree it was living in is removed
* (`resetDisplacedCwd`). It is caught by path wherever it sits, like an editor and unlike a
* terminal, because it has no session to disturb — and it is re-pointed rather than flagged
* `fileMissing`, because a directory can be re-pointed and a dead file cannot.
*
* `null` means LEAVE IT ALONE, and that is the interesting answer: with no fallback directory
* there is nowhere honest to send it, and writing `undefined` is worse than doing nothing — the
* node would lose the only thing it knows about itself. Left on the dead path, the parent-listing
* probe usually says "Could not read this folder", which is the truth.
*
* Two honest caveats. The branch is near-unreachable in practice (a worktree binding cannot exist
* without a project cwd, so a fallback almost always exists). And "usually": `git worktree remove`
* deletes the worktree but not the now-empty `<repo>.worktrees/` container, so removing the LAST
* one leaves the probe with an empty parent — `unknown`, which still renders as "empty". Doing
* nothing is still better than writing a path we cannot justify.
*
* The title rides along while `titleAuto` holds. This is the one cwd write that does NOT go
* through `navigate` — the only other place that pairs the two — so without it the node moves to
* a new directory still wearing the removed worktree's name.
*/
export function displacedFilesPatch(
data: { titleAuto?: unknown },
fallbackCwd: string | undefined
): { cwd: string; title?: string } | null {
if (!fallbackCwd) return null
return data.titleAuto !== false
? { cwd: fallbackCwd, title: folderTitle(fallbackCwd) }
: { cwd: fallbackCwd }
}
export type EmptyListingVerdict = 'empty' | 'missing' | 'unreachable' | 'unknown'
/**
* What an EMPTY listing actually means.
*
* `FsApi` is fail-open by contract — `core/fs-ops.listDir` and `SshFs.listDir` both end
* `catch { return [] }`, and the SSH IPC resolves `[]` even for a project whose ControlMaster is
* down. So a `.catch` on `list()` fires only when the transport itself rejects, and a directory
* that was deleted (a removed worktree, most obviously) comes back indistinguishable from one
* that is genuinely empty. That is why the node's "could not read" state was unreachable.
*
* We do not ask `fs.exists`. It is `stat`-based, so it answers TRUE for a directory you can stat
* but not `readdir`, and on SSH its `false` cannot separate "gone" from "the master died" — which
* `SshFs.readTextChecked` singles out precisely so it can refuse to conflate them: *a failed read
* is never evidence of absence*. Instead we ask the PARENT's listing, the same way
* `SshProjectDialog` and `file-links.ts`'s `makeDirListingLookup` already answer this question.
*
* Four answers, and the last two are the point:
* - `missing` — the parent listed real entries and ours is not among them. Only this earns the
* error state.
* - `empty` — the parent lists us, so the directory is there and simply has nothing in it.
* Root takes this too: it has no parent to ask and always exists.
* - `unreachable` — the parent came back empty or could not be read at all. It cannot be
* childless, since it contains us, so this says we could not see the filesystem. We still
* cannot tell "the whole subtree is gone" from "the connection is down", so the verdict names
* the doubt instead of guessing.
* - `unknown` — the path SHAPE means no parent listing could ever answer (see below). Genuinely
* no information, so the caller keeps saying "empty". Understating beats telling someone their
* folder was deleted because a network hiccup ate one `ls`.
*
* Matching is by NAME, not by `dir`, deliberately: a symlinked directory can list as a non-dir
* entry depending on the leg, and mistaking one for "missing" is the false alarm this exists to
* avoid.
*/
export function classifyEmptyListing(
cwd: string,
/** The parent's entries, or `null` when the parent was not asked or could not be read. */
parentEntries: readonly { name: string }[] | null
): EmptyListingVerdict {
const trimmed = cwd.replace(/\/+$/, '')
const name = folderTitle(cwd)
if (name === '/' || !trimmed) return 'empty' // root: no parent, always exists
// Below are the paths whose parent listing CANNOT answer the question. Each of them would
// otherwise fail to name-match and be reported as `missing` — a false "your folder is gone" on a
// directory that is perfectly readable, which is the one error this whole classifier exists to
// avoid making.
//
// - Not `/`-absolute. `~` is the big one: an SSH project's `remoteCwd` DEFAULTS to `~`
// (SshSection), `ls ~` works fine on the host, but `parentDir('~')` is `/` and `/` has no
// entry called `~`. So an empty remote HOME reported "Could not read this folder."
// - `.` / `..` segments — `readdir` and `ls -A` never emit them.
// - `.git`, which BOTH listing legs strip on purpose (`core/fs-ops.ts`, `main/ssh-fs.ts`), so a
// node pointed at one can never find itself in its parent.
if (!trimmed.startsWith('/') || name === '.' || name === '..' || name === '.git') return 'unknown'
// The parent could not be read. Note it cannot legitimately be EMPTY either: it contains the
// directory we are standing in, so an empty listing means we could not see it, exactly as the
// fail-open contract allows. That is real information and it used to be thrown away as
// `unknown`, leaving the node saying "This folder is empty." over a dead ControlMaster, which
// is the most common cause of an empty remote listing and the most reassuring possible lie.
//
// We still cannot say WHICH (the whole subtree deleted, or the filesystem out of reach), so the
// verdict names the doubt rather than picking one.
if (!parentEntries || parentEntries.length === 0) return 'unreachable'
if (parentEntries.some((e) => e.name === name)) return 'empty'
// A case-insensitive filesystem (APFS, NTFS) lists a directory fine under a cwd whose case
// differs from the on-disk spelling, and `readdir` answers with the on-disk one. Treat that as
// present: a case-folded match is weaker evidence of existence, but "missing" needs to be the
// conclusion we are SURE of.
const lower = name.toLowerCase()
if (parentEntries.some((e) => e.name.toLowerCase() === lower)) return 'empty'
return 'missing'
}
/** Join a directory and an entry name. Trailing slashes on the dir are absorbed, so the root
* ('/') does not produce a doubled separator. */
export function childPath(dir: string, name: string): string {
return `${dir.replace(/\/+$/, '')}/${name}`
}
/**
* Filter listed entries by a substring, case-insensitively. An empty or whitespace-only query
* matches everything — a filter box that silently hides the whole listing when the user selects
* and deletes their text is the bug this guards.
*/
export function filterEntries<T extends { name: string }>(entries: T[], query: string): T[] {
const q = query.trim().toLowerCase()
if (!q) return entries
return entries.filter((e) => e.name.toLowerCase().includes(q))
}
/**
* What opening a FILE should do.
*
* `canvas` — open it as a node on the canvas (an editor for text and images, a video player for
* media). This is what the canvas `nodeterm:open-file` listener already does.
* `os` — hand it to the operating system's default application, for the things Monaco can
* only render as garbage: archives, installers, databases, binaries.
*
* `remote` (an SSH project, or a relay tab) forces `canvas`, and that is not a limitation dressed
* up as a choice: `shell.openPath` opens a path on THIS machine, so handing it a path that exists
* on another one either fails silently or — worse, if the path happens to exist here too — opens
* a completely unrelated local file. The same rule Canvas's own `openProjectFile` follows.
*/
export function fileOpenTarget(path: string, opts: { remote?: boolean } = {}): 'canvas' | 'os' {
if (opts.remote) return 'canvas'
if (isMediaFile(path)) return 'canvas'
return opensInEditor(path) ? 'canvas' : 'os'
}
/** One Download row in a files node's context menu. `pickFolder` = ask for a destination first
* ("Download to…"), which only the desktop scp route can honour. */
export interface DownloadMenuEntry {
label: string
pickFolder: boolean
}
/**
* The Download rows a files node's context menu offers for `path`. Where the route is `none`
* (a desktop local project — the file is already here — or a relay tab) there are none, and so
* for a path that cannot name a download: the node can stand on `/`, and a "Download this folder"
* there would stream the whole server filesystem.
*
* `here` = the menu was opened on empty space, so `path` is the folder being shown rather than a
* row in it — named as such, because "Download folder" over a blank area does not say which one.
* An HTTP folder download arrives as a `.tar.gz` (the server archives it on the fly) and the label
* says so; scp brings a folder down AS a folder.
*/
export function downloadMenuEntries(
route: DownloadRoute,
path: string,
{ dir, here }: { dir: boolean; here: boolean }
): DownloadMenuEntry[] {
if (route === 'none' || !isDownloadablePath(path)) return []
const what = dir ? (here ? 'Download this folder' : 'Download folder') : 'Download'
const entries: DownloadMenuEntry[] = [
{ label: dir && route === 'http' ? `${what} (.tar.gz)` : what, pickFolder: false }
]
// The browser has no native folder picker, and where its downloads land is a browser setting.
if (route === 'scp') entries.push({ label: 'Download to…', pickFolder: true })
return entries
}
/**
* How long a pause ends a type-ahead word. Typing "bu" within this window searches for "bu…";
* after it, the next key starts over.
*/
export const TYPEAHEAD_RESET_MS = 1000
/**
* Windows-Explorer type-ahead: the index of the entry `buffer` selects, or -1 for no match.
*
* - One letter — or the same letter repeated ("b", "bb") — CYCLES: the next entry after
* `current` starting with it, wrapping. That is how pressing B three times walks the B's.
* - A word ("bui") is a prefix search from `current` INCLUSIVE, so extending a word that still
* matches the selected entry keeps it rather than jumping past it.
*
* Case-insensitive; `current` is -1 when nothing is selected.
*/
export function typeAheadIndex(names: readonly string[], current: number, buffer: string): number {
if (!buffer || names.length === 0) return -1
const q = buffer.toLowerCase()
const cycling = [...q].every((c) => c === q[0])
const needle = cycling ? q[0] : q
const start = cycling ? current + 1 : Math.max(current, 0)
for (let i = 0; i < names.length; i++) {
const idx = (start + i) % names.length
if (names[idx].toLowerCase().startsWith(needle)) return idx
}
return -1
}
export interface TypeAheadState {
buffer: string
/** When the last key was typed (ms). */
at: number
}
/** Fold one typed key into the type-ahead word and resolve what it selects. */
export function typeAhead(
state: TypeAheadState,
key: string,
now: number,
names: readonly string[],
current: number
): { state: TypeAheadState; index: number } {
const buffer = (now - state.at > TYPEAHEAD_RESET_MS ? '' : state.buffer) + key
return { state: { buffer, at: now }, index: typeAheadIndex(names, current, buffer) }
}
export type ListKeyAction = { kind: 'select'; index: number } | { kind: 'open'; index: number } | { kind: 'up' } | null
/**
* What a navigation key does in a files node's listing. `current` is the selected index (-1 for
* none) and `count` the number of entries shown. Windows and Finder chords both work, because a
* user reaches for whichever their hands know: Enter / ⌘↓ open, Backspace / Alt+↑ / ⌘↑ go up.
* `null` = not a listing key; the caller lets it through.
*/
export function listKeyAction(
e: { key: string; alt?: boolean; meta?: boolean; ctrl?: boolean },
current: number,
count: number
): ListKeyAction {
if (e.ctrl) return null
if (e.key === 'ArrowUp' && (e.alt || e.meta)) return { kind: 'up' }
if (e.key === 'ArrowDown' && e.meta) return current >= 0 ? { kind: 'open', index: current } : null
if (e.alt || e.meta) return null
if (e.key === 'Backspace') return { kind: 'up' }
if (e.key === 'Enter') return current >= 0 ? { kind: 'open', index: current } : null
if (count === 0) return null
const last = count - 1
switch (e.key) {
case 'ArrowDown':
return { kind: 'select', index: current < 0 ? 0 : Math.min(current + 1, last) }
case 'ArrowUp':
return { kind: 'select', index: current < 0 ? last : Math.max(current - 1, 0) }
case 'Home':
return { kind: 'select', index: 0 }
case 'End':
return { kind: 'select', index: last }
default:
return null
}
}
/**
* The entry of `to` that leads back toward `from`, when `to` is a strict ancestor of it — so going
* up (the ↑ button, Backspace, a breadcrumb) lands with the folder you came out of selected, the
* way Windows Explorer and Finder do. `null` when `to` is not an ancestor (entering a subfolder,
* or a jump elsewhere), which means "select nothing".
*/
export function childOnPath(to: string, from: string): string | null {
if (to.startsWith('/') !== from.startsWith('/')) return null
const a = to.split('/').filter(Boolean)
const b = from.split('/').filter(Boolean)
if (b.length <= a.length) return null
for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return null
return b[a.length]
}
/**
* The list's `scrollTop` that brings a row fully into view, moving as little as possible (the
* `block: 'nearest'` rule). Computed by hand rather than with `scrollIntoView`, which also scrolls
* every scrollable ANCESTOR — inside the canvas that includes React Flow's own overflow:hidden
* containers, and it would shove the whole pane sideways under a transformed viewport.
* All values are layout pixels (offsetTop/offsetHeight/clientHeight), so canvas zoom is irrelevant.
*/
export function scrollTopToReveal(rowTop: number, rowHeight: number, scrollTop: number, viewHeight: number): number {
if (rowTop < scrollTop) return rowTop
if (rowTop + rowHeight > scrollTop + viewHeight) return rowTop + rowHeight - viewHeight
return scrollTop
}