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, beforeEach, afterEach } from 'vitest'
import fs from 'fs'
import os from 'os'
import path from 'path'
import { execFileSync } from 'child_process'
import {
directExecutableInvocation,
envPathKey,
executableCandidates,
findInPathString,
unquotePathEntry
} from './exec-path'
describe('executableCandidates', () => {
it('leaves a bare name alone off win32 — POSIX has no PATHEXT', () => {
expect(executableCandidates('gh', 'darwin', undefined)).toEqual(['gh'])
expect(executableCandidates('gh', 'linux', '.EXE')).toEqual(['gh'])
})
it('appends PATHEXT on win32, extensions first and the bare name last', () => {
// The regression this closes: `gh` on Windows is `gh.exe`, so a bare-name-only walk found
// nothing and every caller fell through to its POSIX fallbacks. The ORDER is load-bearing too
// — see the shim test below.
expect(executableCandidates('gh', 'win32', '.COM;.EXE;.CMD')).toEqual([
'gh.COM',
'gh.EXE',
'gh.CMD',
'gh'
])
})
it('falls back to the stock PATHEXT when the variable is missing or empty', () => {
expect(executableCandidates('ssh', 'win32', undefined)).toEqual([
'ssh.COM',
'ssh.EXE',
'ssh.BAT',
'ssh.CMD',
'ssh'
])
expect(executableCandidates('ssh', 'win32', '')).toEqual(
executableCandidates('ssh', 'win32', undefined)
)
})
it('tolerates whitespace and empty entries in PATHEXT', () => {
expect(executableCandidates('gh', 'win32', ' .EXE ; ; .CMD ')).toEqual([
'gh.EXE',
'gh.CMD',
'gh'
])
})
it('does not double up on a name that already carries an extension', () => {
expect(executableCandidates('gh.exe', 'win32', '.COM;.EXE')).toEqual(['gh.exe'])
// Case-insensitively: Windows does not care, and neither should the guard.
expect(executableCandidates('claude.CMD', 'win32', '.EXE;.cmd')).toEqual(['claude.CMD'])
})
})
describe('unquotePathEntry', () => {
it('strips the quotes Windows tolerates around a PATH entry', () => {
expect(unquotePathEntry('"C:\\Program Files\\GitHub CLI"')).toBe('C:\\Program Files\\GitHub CLI')
})
it('leaves an unquoted entry and a lone quote untouched', () => {
expect(unquotePathEntry('/usr/bin')).toBe('/usr/bin')
expect(unquotePathEntry('"C:\\half')).toBe('"C:\\half')
})
})
describe('directExecutableInvocation', () => {
const systemRoot = 'C:\\Windows'
const cmd = `${systemRoot}\\System32\\cmd.exe`
it('leaves native and non-Windows executables unchanged', () => {
expect(
directExecutableInvocation('C:\\Tools\\agent.exe', ['--version'], {
platform: 'win32',
systemRoot,
exists: () => false
})
).toEqual({ executable: 'C:\\Tools\\agent.exe', args: ['--version'] })
expect(
directExecutableInvocation('/usr/bin/agent.cmd', ['--version'], { platform: 'linux' })
).toEqual({ executable: '/usr/bin/agent.cmd', args: ['--version'] })
})
it('runs a Windows cmd shim through hidden cmd.exe with escaped verbatim arguments', () => {
expect(
directExecutableInvocation('C:\\Tools\\agent.CMD', ['--flag', 'value & untouched'], {
platform: 'win32',
systemRoot,
exists: (candidate) => candidate.toLowerCase() === cmd.toLowerCase()
})
).toEqual({
executable: cmd,
args: [
'/d',
'/s',
'/v:off',
'/c',
'"C:\\Tools\\agent.CMD ^^^"--flag^^^" ^^^"value^^^ ^^^&^^^ untouched^^^""'
],
options: { windowsHide: true, windowsVerbatimArguments: true }
})
})
it('fails closed without cmd.exe and for unsupported Windows script kinds', () => {
expect(
directExecutableInvocation('C:\\Tools\\agent.cmd', [], {
platform: 'win32',
systemRoot,
exists: () => false
})
).toBeNull()
expect(
directExecutableInvocation('C:\\Tools\\agent.bat', [], {
platform: 'win32',
systemRoot,
exists: () => true
})
).toBeNull()
expect(
directExecutableInvocation('C:\\Tools\\agent.ps1', [], {
platform: 'win32',
systemRoot,
exists: () => true
})
).toBeNull()
})
it('fails closed when cmd.exe cannot preserve argv or the command exceeds its limit', () => {
const options = { platform: 'win32' as const, systemRoot, exists: () => true }
expect(directExecutableInvocation('C:\\Tools\\agent.cmd', ['line 1\nline 2'], options)).toBeNull()
expect(directExecutableInvocation('C:\\Tools\\agent.cmd', ['line 1\rline 2'], options)).toBeNull()
expect(directExecutableInvocation('C:\\Tools\\agent.cmd', ['nul\0byte'], options)).toBeNull()
expect(directExecutableInvocation('C:\\Tools\\agent.cmd', ['x'.repeat(8100)], options)).toBeNull()
})
})
describe.skipIf(process.platform !== 'win32')('directExecutableInvocation - real cmd shim', () => {
it('preserves npm-shim argv boundaries and cmd metacharacters', () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-exec-shim-'))
try {
const shimDir = path.join(dir, 'shims & !tools!')
fs.mkdirSync(shimDir)
const script = path.join(shimDir, 'capture.js')
const cmd = path.join(shimDir, 'capture args.cmd')
fs.writeFileSync(script, 'process.stdout.write(JSON.stringify(process.argv.slice(2)))\n')
fs.writeFileSync(cmd, `@echo off\r\n"${process.execPath}" "${script}" %*\r\n`)
const args = [
'',
'plain',
'space value',
'embedded "quote"',
'trailing\\',
'before\\"after',
'&|<>()@^',
'%PATH%',
'!delayed!',
'café 日本語'
]
const invocation = directExecutableInvocation(cmd, args)
expect(invocation).not.toBeNull()
const output = execFileSync(invocation!.executable, invocation!.args, {
...invocation!.options,
encoding: 'utf8'
})
expect(JSON.parse(output)).toEqual(args)
} finally {
fs.rmSync(dir, { recursive: true, force: true })
}
})
})
// End-to-end over the real filesystem: the unit tests above prove the NAME mapping, these prove the
// walk actually resolves those names — the half that was broken. Split by platform because the
// mapping they exercise only exists on one of them.
describe('findInPathString (real filesystem)', () => {
let dir: string
beforeEach(() => {
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-exec-path-'))
})
afterEach(() => {
fs.rmSync(dir, { recursive: true, force: true })
})
/** POSIX needs the exec bit for X_OK; on Windows the mode is ignored and F_OK is what we ask. */
const writeBin = (name: string): string => {
const p = path.join(dir, name)
fs.writeFileSync(p, '', { mode: 0o755 })
return p
}
/** A win32 hit carries PATHEXT's casing (`.EXE`), not the file's own — the same path, since
* Windows is case-insensitive. Compare the way the platform does. */
const expectPath = (got: string | null, want: string): void => {
expect(process.platform === 'win32' ? got?.toLowerCase() : got).toBe(
process.platform === 'win32' ? want.toLowerCase() : want
)
}
it('finds an executable that is on the PATH, and answers null for one that is not', () => {
const bin = process.platform === 'win32' ? 'nt-probe.exe' : 'nt-probe'
writeBin(bin)
expectPath(findInPathString(process.platform === 'win32' ? 'nt-probe' : bin, dir), path.join(dir, bin))
expect(findInPathString('nt-absent', dir)).toBeNull()
})
it('skips empty entries and searches later ones', () => {
const bin = process.platform === 'win32' ? 'nt-probe.exe' : 'nt-probe'
writeBin(bin)
const pathStr = ['', path.join(dir, 'nope'), dir].join(path.delimiter)
expectPath(findInPathString(process.platform === 'win32' ? 'nt-probe' : bin, pathStr), path.join(dir, bin))
})
it('tolerates a quoted PATH entry', () => {
const bin = process.platform === 'win32' ? 'nt-probe.exe' : 'nt-probe'
writeBin(bin)
expectPath(
findInPathString(process.platform === 'win32' ? 'nt-probe' : bin, `"${dir}"`),
path.join(dir, bin)
)
})
// The regression itself: a bare name must reach `<name>.exe` / `<name>.cmd` on disk. `gh` really
// is `gh.exe` and an npm shim really is `<name>.cmd`, and resolving neither is what left Windows
// with no gh, no ssh and a claude probe that never ran.
describe.skipIf(process.platform !== 'win32')('win32 PATHEXT', () => {
it('resolves a bare name to its .exe and .cmd on disk', () => {
writeBin('nt-exe-only.exe')
writeBin('nt-cmd-only.cmd')
expectPath(findInPathString('nt-exe-only', dir), path.join(dir, 'nt-exe-only.exe'))
expectPath(findInPathString('nt-cmd-only', dir), path.join(dir, 'nt-cmd-only.cmd'))
})
it('prefers the PATHEXT match over an extensionless shim in the same directory', () => {
// Exactly what npm lays down for a global CLI on Windows: `<name>` is a POSIX shell shim for
// Git Bash and `<name>.cmd` is the one cmd/CreateProcess can actually run. Preferring the
// bare name here returns a file that exists and cannot be spawned.
writeBin('nt-shim')
writeBin('nt-shim.cmd')
expectPath(findInPathString('nt-shim', dir), path.join(dir, 'nt-shim.cmd'))
})
it('falls back to an extensionless file when nothing matches PATHEXT', () => {
// An extensionless PE is executable, so it stays a last resort rather than being ignored.
writeBin('nt-bare-only')
expectPath(findInPathString('nt-bare-only', dir), path.join(dir, 'nt-bare-only'))
})
it('still finds a name given in full', () => {
writeBin('nt-full.exe')
expectPath(findInPathString('nt-full.exe', dir), path.join(dir, 'nt-full.exe'))
})
})
})
describe('envPathKey', () => {
it('uses the key the environment already has', () => {
expect(envPathKey({ PATH: '/bin' })).toBe('PATH')
expect(envPathKey({ Path: 'C:\\Windows' })).toBe('Path')
expect(envPathKey({ path: 'x' })).toBe('path')
})
it('prefers an exact PATH and defaults to PATH', () => {
expect(envPathKey({ Path: 'a', PATH: 'b' })).toBe('PATH')
expect(envPathKey({})).toBe('PATH')
})
})