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 { spawn, type ChildProcess } from 'node:child_process'
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { fakePlatform } from './platform-fake'
import { initPlatform, resetPlatformForTests } from './platform'
import {
bootSimulatorWith,
discoverProjects,
flutterPidFile,
launcherPath,
listEntries,
runStatus,
setWatch,
simctlSetupError,
signalRun,
startRun,
stopAllRunWatches,
stopRun
} from './run-service'
const PUBSPEC = 'name: app\ndependencies:\n flutter:\n sdk: flutter\n'
const NODE = process.execPath
const posix = process.platform !== 'win32'
let root: string
let children: ChildProcess[] = []
function write(rel: string, text: string): string {
const p = path.join(root, rel)
mkdirSync(path.dirname(p), { recursive: true })
writeFileSync(p, text)
return p
}
async function until(fn: () => boolean | Promise<boolean>, ms = 6000): Promise<void> {
const end = Date.now() + ms
while (!(await fn())) {
if (Date.now() > end) throw new Error('timed out')
await new Promise((r) => setTimeout(r, 40))
}
}
/** Run the launcher the way the node's shell would: its own job (process group), like `sh x` typed
* at an interactive prompt. */
function runLauncher(nodeId: string): ChildProcess {
const child = spawn('/bin/sh', [launcherPath(nodeId)], { detached: true, stdio: 'ignore' })
children.push(child)
return child
}
describe('run-service', () => {
beforeEach(() => {
initPlatform(fakePlatform())
root = mkdtempSync(path.join(os.tmpdir(), 'nt-run-'))
})
afterEach(() => {
stopAllRunWatches()
for (const c of children) {
try {
process.kill(-(c.pid as number), 'SIGKILL')
} catch {
/* gone */
}
}
children = []
rmSync(root, { recursive: true, force: true })
resetPlatformForTests()
})
it('lists described entries, and offers plain flutter run to a Flutter checkout with no launch.json', async () => {
const api = path.join(root, 'api')
write('api/.vscode/launch.json', `{ "configurations": [
{ "name": "API", "type": "node", "request": "launch", "program": "a.js" },
{ "name": "Attach", "type": "node", "request": "attach" },
], "compounds": [ { "name": "All", "configurations": ["API"] } ] }`)
const r = await listEntries(api)
expect(r.found).toBe(true)
expect(r.entries.map((e) => [e.name, e.kind, e.supported])).toEqual([
['API', 'config', true],
['Attach', 'config', false],
['All', 'compound', true]
])
write('app/pubspec.yaml', PUBSPEC)
const flutter = await listEntries(path.join(root, 'app'))
expect(flutter).toMatchObject({ found: false, isFlutterProject: true })
expect(flutter.entries.map((e) => e.typeLabel)).toEqual(['Flutter'])
write('broken/.vscode/launch.json', '{ nope')
expect((await listEntries(path.join(root, 'broken'))).error).toMatch(/Could not parse/)
})
it('finds runnable folders beside the project, worktrees included', async () => {
write('api/.vscode/launch.json', '{}')
write('doc-flutter/pubspec.yaml', PUBSPEC)
write('doc-flutter.worktrees/feature/pubspec.yaml', PUBSPEC)
write('notes/readme.md', 'x')
const found = await discoverProjects(path.join(root, 'notes'))
expect(found.map((d) => path.relative(root, d))).toEqual([
'api',
'doc-flutter',
path.join('doc-flutter.worktrees', 'feature')
])
})
it('refuses with a sentence: no folder, no config, unsupported config; answers compounds and urls', async () => {
write('w/.vscode/launch.json', `{ "configurations": [
{ "name": "Attach", "type": "node", "request": "attach" },
{ "name": "Web", "type": "chrome", "request": "launch", "url": "http://localhost:3000" },
], "compounds": [ { "name": "Both", "configurations": ["Web", "Attach"] } ] }`)
const w = path.join(root, 'w')
expect(await startRun('n1', { projectDir: path.join(root, 'gone'), reloadOnSave: true })).toMatchObject({ ok: false })
expect(await startRun('n1', { projectDir: w, launchConfig: 'Nope', reloadOnSave: true })).toEqual({
ok: false,
error: '“Nope” is not in .vscode/launch.json.'
})
expect(await startRun('n1', { projectDir: w, launchConfig: 'Attach', reloadOnSave: true })).toMatchObject({
ok: false,
error: expect.stringMatching(/attaches/)
})
expect(await startRun('n1', { projectDir: w, launchConfig: 'Web', reloadOnSave: true })).toEqual({
ok: true,
kind: 'browser',
url: 'http://localhost:3000'
})
expect(await startRun('n1', { projectDir: w, launchConfig: 'Both', reloadOnSave: true })).toEqual({
ok: true,
kind: 'compound',
members: ['Web', 'Attach']
})
expect(await startRun('../x', { projectDir: w, reloadOnSave: true })).toMatchObject({ ok: false })
})
it('switch mode writes a flutter attach launcher; refuses non-Flutter runs and apps that read appFlavor', async () => {
write('app/pubspec.yaml', PUBSPEC)
write('app/lib/main_dev.dart', 'void main() {}')
write('app/.vscode/launch.json', `{ "configurations": [
{ "name": "Dev", "type": "dart", "request": "launch", "program": "lib/main_dev.dart", "args": ["--flavor", "dev", "--web-port=8080"] },
{ "name": "Tool", "type": "node", "request": "launch", "program": "a.js" }
] }`)
const app = path.join(root, 'app')
const r = await startRun('n8', { projectDir: app, launchConfig: 'Dev', deviceId: 'SIM-1', reloadOnSave: true }, { attach: true })
expect(r).toMatchObject({ ok: true, kind: 'process', hotReload: true })
const script = readFileSync(launcherPath('n8'), 'utf8')
expect(script).toContain(`'flutter' 'attach' '-t' 'lib/main_dev.dart' '-d' 'SIM-1' '--pid-file' '${flutterPidFile('n8')}'`)
expect(script).not.toContain('--flavor')
expect(script).not.toContain('--web-port')
expect(await startRun('n8', { projectDir: app, launchConfig: 'Tool', reloadOnSave: true }, { attach: true })).toMatchObject({
ok: false,
error: expect.stringMatching(/not a Flutter run/)
})
write('app/lib/flavor.dart', "import 'package:flutter/services.dart'; final f = appFlavor;")
expect(await startRun('n8', { projectDir: app, launchConfig: 'Dev', deviceId: 'SIM-1', reloadOnSave: true }, { attach: true })).toEqual({
ok: false,
error: 'This app reads appFlavor, which flutter attach cannot set — rebuild to switch.'
})
})
describe('on a Windows core', () => {
const real = Object.getOwnPropertyDescriptor(process, 'platform') as PropertyDescriptor
beforeEach(() => Object.defineProperty(process, 'platform', { value: 'win32' }))
afterEach(() => Object.defineProperty(process, 'platform', real))
it('still opens browser configs and browser-only compounds, and refuses a process run with a sentence', async () => {
write('w/.vscode/launch.json', `{ "configurations": [
{ "name": "Web", "type": "chrome", "request": "launch", "url": "http://localhost:3000" },
{ "name": "API", "type": "node", "request": "launch", "program": "a.js" },
], "compounds": [
{ "name": "Pages", "configurations": ["Web"] },
{ "name": "Stack", "configurations": ["Web", "API"] }
] }`)
const w = path.join(root, 'w')
expect(await startRun('n1', { projectDir: w, launchConfig: 'Web', reloadOnSave: true })).toEqual({
ok: true,
kind: 'browser',
url: 'http://localhost:3000'
})
expect(await startRun('n1', { projectDir: w, launchConfig: 'Pages', reloadOnSave: true })).toEqual({
ok: true,
kind: 'compound',
members: ['Web']
})
const refused = { ok: false, error: 'Run configurations that launch a process are not supported on Windows yet.' }
expect(await startRun('n1', { projectDir: w, launchConfig: 'API', reloadOnSave: true })).toEqual(refused)
expect(await startRun('n1', { projectDir: w, launchConfig: 'Stack', reloadOnSave: true })).toEqual(refused)
expect(existsSync(launcherPath('n1'))).toBe(false)
// The listing says so before Start, so the bar disables Run with the reason.
const r = await listEntries(w)
expect(r.entries.map((e) => [e.name, e.supported])).toEqual([
['Web', true],
['API', false],
['Pages', true],
['Stack', false]
])
})
})
it.skipIf(!posix)('runs the preLaunchTask, then the program with env + envFile, and records the exit code', async () => {
const w = path.join(root, 'w')
const out = path.join(root, 'out.txt')
// Fixture scripts are FIXED source: anything run-specific (paths) reaches them as env, never
// spliced into the code.
write(
'w/app.js',
"require('fs').writeFileSync(process.env.OUT, [process.env.FROM_CFG, process.env.FROM_FILE, process.env.SHARED, process.cwd(), process.argv.slice(2).join(',')].join('|')); process.exit(3)"
)
write('w/.env', 'FROM_FILE=file-value\nSHARED=from-file\n')
write('w/.vscode/tasks.json', `{ "tasks": [ { "label": "prep", "type": "shell", "command": "echo prepped > prep.txt" } ] }`)
write('w/.vscode/launch.json', `{ "configurations": [ {
"name": "API", "type": "node", "request": "launch",
"runtimeExecutable": ${JSON.stringify(NODE)},
"program": "\${workspaceFolder}/app.js", "args": ["a", "b c"],
"env": { "FROM_CFG": "cfg-value", "SHARED": "from-config", "OUT": ${JSON.stringify(out)} },
"envFile": "\${workspaceFolder}/.env",
"preLaunchTask": "prep"
} ] }`)
const r = await startRun('n2', { projectDir: w, launchConfig: 'API', reloadOnSave: true, extraArgs: '--extra' })
expect(r).toMatchObject({ ok: true, kind: 'process', hotReload: false })
if (!r.ok || r.kind !== 'process') return
expect(r.command).toBe(`sh '${launcherPath('n2')}'`)
// Owner-only: the launcher can carry an envFile's secrets.
expect(statSync(launcherPath('n2')).mode & 0o077).toBe(0)
runLauncher('n2')
await until(async () => (await runStatus('n2')).exitCode !== null)
expect(await runStatus('n2')).toEqual({ running: false, exitCode: 3 })
expect(readFileSync(path.join(w, 'prep.txt'), 'utf8').trim()).toBe('prepped')
expect(readFileSync(out, 'utf8')).toBe(`cfg-value|file-value|from-config|${w}|a,b c,--extra`)
})
it.skipIf(!posix)('a failing preLaunchTask stops the run with its status', async () => {
const w = path.join(root, 'w')
write('w/.vscode/tasks.json', `{ "tasks": [ { "label": "fail", "type": "shell", "command": "exit 7" } ] }`)
write('w/.vscode/launch.json', `{ "configurations": [ { "name": "X", "type": "node", "request": "launch",
"runtimeExecutable": ${JSON.stringify(NODE)}, "program": "nope.js", "preLaunchTask": "fail" } ] }`)
expect((await startRun('n3', { projectDir: w, launchConfig: 'X', reloadOnSave: true })).ok).toBe(true)
runLauncher('n3')
await until(async () => (await runStatus('n3')).exitCode !== null)
expect(await runStatus('n3')).toEqual({ running: false, exitCode: 7 })
})
it.skipIf(!posix)('reports a live run, and Stop interrupts it like Ctrl+C', async () => {
const w = path.join(root, 'w')
const marker = path.join(root, 'got-int')
const ready = path.join(root, 'ready')
write(
'w/serve.js',
"const fs = require('fs'); process.on('SIGINT', () => { fs.writeFileSync(process.env.MARKER, 'x'); process.exit(130) }); fs.writeFileSync(process.env.READY, 'x'); setInterval(() => {}, 1000)"
)
write('w/.vscode/launch.json', JSON.stringify({
configurations: [
{ name: 'S', type: 'node', request: 'launch', runtimeExecutable: NODE, program: 'serve.js', env: { MARKER: marker, READY: ready } }
]
}))
await startRun('n4', { projectDir: w, launchConfig: 'S', reloadOnSave: true })
runLauncher('n4')
await until(async () => (await runStatus('n4')).running)
// The launcher is live before the program has installed its handler; wait for the program.
await until(() => existsSync(ready))
expect(await stopRun('n4')).toBe(true)
await until(async () => !(await runStatus('n4')).running)
expect(existsSync(marker)).toBe(true)
expect((await runStatus('n4')).exitCode).toBe(130)
expect(await stopRun('n4')).toBe(false)
})
it.skipIf(!posix)('hot reload / restart signal only a live flutter process', async () => {
let out = ''
const fake = spawn(
NODE,
['-e', "process.on('SIGUSR1',()=>console.log('RELOAD'));process.on('SIGUSR2',()=>console.log('RESTART'));console.log('UP');setInterval(()=>{},1000)", 'flutter_tools.snapshot'],
{ stdio: ['ignore', 'pipe', 'ignore'], detached: true }
)
children.push(fake)
fake.stdout!.on('data', (d) => (out += String(d)))
await until(() => out.includes('UP'))
mkdirSync(path.dirname(flutterPidFile('n5')), { recursive: true })
writeFileSync(flutterPidFile('n5'), String(fake.pid))
expect(await signalRun('n5', 'reload')).toBe(true)
await until(() => out.includes('RELOAD'))
expect(await signalRun('n5', 'restart')).toBe(true)
await until(() => out.includes('RESTART'))
// A pid file naming a process that is not flutter (this test runner) is never signalled.
writeFileSync(flutterPidFile('n6'), String(process.pid))
expect(await signalRun('n6', 'reload')).toBe(false)
})
it.skipIf(!posix)('reload on save: one hot reload per burst of .dart changes under lib/', async () => {
write('app/lib/main.dart', 'void main() {}')
let out = ''
const fake = spawn(NODE, ['-e', "process.on('SIGUSR1',()=>console.log('RELOAD'));console.log('UP');setInterval(()=>{},1000)", 'flutter_tools.snapshot'], {
stdio: ['ignore', 'pipe', 'ignore'],
detached: true
})
children.push(fake)
fake.stdout!.on('data', (d) => (out += String(d)))
await until(() => out.includes('UP'))
mkdirSync(path.dirname(flutterPidFile('n7')), { recursive: true })
writeFileSync(flutterPidFile('n7'), String(fake.pid))
setWatch('n7', path.join(root, 'app'))
await new Promise((r) => setTimeout(r, 150))
write('app/lib/notes.txt', 'ignored')
write('app/lib/a.dart', 'void a() {}')
write('app/lib/b.dart', 'void b() {}')
await until(() => out.includes('RELOAD'))
await new Promise((r) => setTimeout(r, 600))
expect(out.match(/RELOAD/g)).toHaveLength(1)
setWatch('n7', null)
write('app/lib/c.dart', 'void c() {}')
await new Promise((r) => setTimeout(r, 700))
expect(out.match(/RELOAD/g)).toHaveLength(1)
})
})
describe('bootSimulatorWith', () => {
const UDID = '12345678-1234-1234-1234-123456789ABC'
function recorder(fail?: string) {
const calls: string[] = []
const exec = async (file: string, args: string[]) => {
calls.push([file, ...args].join(' '))
if (fail) throw Object.assign(new Error('x'), { stderr: fail })
}
return { calls, exec }
}
it('opens Simulator.app after booting, as a run node always has', async () => {
const r = recorder()
expect(await bootSimulatorWith(UDID, {}, r.exec)).toBe(true)
expect(r.calls).toEqual([`/usr/bin/xcrun simctl boot ${UDID}`, '/usr/bin/open -a Simulator'])
})
it('stays headless when the caller is the Simulator node itself', async () => {
const r = recorder()
expect(await bootSimulatorWith(UDID, { openWindow: false }, r.exec)).toBe(true)
expect(r.calls).toEqual([`/usr/bin/xcrun simctl boot ${UDID}`])
})
it('refuses an id that is not a UDID, and a boot that failed', async () => {
const r = recorder()
expect(await bootSimulatorWith('../x', {}, r.exec)).toBe(false)
expect(r.calls).toEqual([])
expect(await bootSimulatorWith(UDID, {}, recorder('No such device').exec)).toBe(false)
})
})
describe('simctlSetupError', () => {
it('turns a missing or unselected Xcode into the fix, and nothing else', () => {
expect(simctlSetupError(Object.assign(new Error('spawn /usr/bin/xcrun ENOENT'), { code: 'ENOENT' }))).toMatch(/xcode-select --switch/)
expect(simctlSetupError({ message: 'Command failed', stderr: 'xcrun: error: unable to find utility "simctl", not a developer tool or in PATH' })).toMatch(/Install Xcode/)
expect(simctlSetupError({ message: 'Command failed', stderr: 'xcode-select: error: tool \'xcrun\' requires Xcode, but active developer directory is a command line tools instance' })).toMatch(/xcode-select/)
expect(simctlSetupError({ message: 'timeout' })).toBeNull()
})
})