Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

18.6 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { EventEmitter } from 'node:events'
import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { dirname, join, win32 } from 'node:path'
import { spawnSync, type ChildProcess } from 'node:child_process'

// Two switches, both off by default: `sh` makes commands run under plain `/bin/sh -c` (as when no user
// shell is known) so output is exactly the command's; `fakeChild` hands runDshCommand a scripted child.
// `started` collects the pid of each real process spawned, for a test that needs the shell's own.
const seams = vi.hoisted(() => ({ sh: false, fakeChild: null as null | (() => ChildProcess), started: [] as Array<number | undefined> }))
vi.mock('../lib/engineLaunch.js', async (importOriginal) => {
  const actual = await importOriginal<typeof import('../lib/engineLaunch.js')>()
  return { ...actual, interactiveEngineShell: (shell?: string) => (seams.sh ? null : actual.interactiveEngineShell(shell)) }
})
vi.mock('node:child_process', async (importOriginal) => {
  const actual = await importOriginal<typeof import('node:child_process')>()
  const spawn = ((...args: Parameters<typeof actual.spawn>) => {
    if (seams.fakeChild) return seams.fakeChild()
    const child = actual.spawn(...args)
    seams.started.push(child.pid)
    return child
  }) as typeof actual.spawn
  return { ...actual, spawn, default: { ...actual, spawn } }
})

const { managedNodePath } = await import('../lib/nodeRuntime.js')
const { dshNodeFallback, dshShellArgv, dshShellAvailable, isKilledJobReport, isShellNoise, killProcessGroup, runDshCommand, spawnDshCommand } = await import('./shell.js')

describe('dshShellArgv', () => {
  const original = process.env.SHELL
  afterEach(() => { if (original === undefined) delete process.env.SHELL; else process.env.SHELL = original })

  it('runs a bash user\'s setup and doctor as a LOGIN shell, where .bash_profile (and nvm) live', () => {
    process.env.SHELL = '/bin/bash'
    expect(dshShellArgv('./doctor.sh')).toEqual({ path: '/bin/bash', args: ['-lic', `${dshNodeFallback()}\n./doctor.sh`] })
  })

  it('keeps zsh as it already was', () => {
    process.env.SHELL = '/bin/zsh'
    expect(dshShellArgv('./doctor.sh')).toEqual({ path: '/bin/zsh', args: ['-lic', `${dshNodeFallback()}\n./doctor.sh`] })
  })

  it('falls back to /bin/sh -c when no user shell is known', () => {
    seams.sh = true
    try {
      expect(dshShellArgv('./doctor.sh')).toEqual({ path: '/bin/sh', args: ['-c', `${dshNodeFallback()}\n./doctor.sh`] })
    } finally {
      seams.sh = false
    }
  })
})

describe('dshShellArgv on Windows', () => {
  const gitBash = () => 'C:\\Program Files\\Git\\bin\\bash.exe'

  it('runs setup and doctor through Git Bash as a login shell, never /bin/sh, which Windows has not', () => {
    const { path, args } = dshShellArgv('./doctor.sh', { platform: 'win32', gitBash })
    expect(path).toBe('C:\\Program Files\\Git\\bin\\bash.exe')
    expect(args).toHaveLength(2)
    expect(args[0]).toBe('-lic')
    expect(args[1].endsWith('\n./doctor.sh')).toBe(true)
  })

  it('says to install Git for Windows when there is no Git Bash, instead of trying a shell that is not there', () => {
    expect(() => dshShellArgv('./doctor.sh', { platform: 'win32', gitBash: () => null }))
      .toThrow('This harness runs a setup or check script, which needs Git Bash on Windows, and it was not found. Install Git for Windows from https://git-scm.com/download/win (or run: winget install --id Git.Git -e), then try again.')
  })

  it('names what could not start when it is a viewer or a workspace init, which are not setup or check scripts', () => {
    expect(() => dshShellArgv('./viewer.sh', { platform: 'win32', gitBash: () => null }, 'viewer'))
      .toThrow("This harness's viewer needs Git Bash on Windows, and it was not found. Install Git for Windows")
    expect(() => dshShellArgv('./init.sh', { platform: 'win32', gitBash: () => null }, 'workspace init'))
      .toThrow("This harness's workspace init needs Git Bash on Windows, and it was not found. Install Git for Windows")
  })

  describe('the script it runs, in a real bash', () => {
    let dir: string
    beforeEach(() => { dir = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-gitbash-'))) })
    afterEach(() => { rmSync(dir, { recursive: true, force: true }) })

    it('ignores a profile\'s `node` alias and finds Harness\'s Node through cygpath when PATH has none', () => {
      // Git Bash profiles can say `alias node='winpty node.exe'`, and winpty fails without a terminal ("stdin is not a
      // tty"). Harness's Node is a C:\ folder, which Git Bash's PATH cannot hold until cygpath writes it as /c/....
      const home = join(dir, 'home'); const stubs = join(dir, 'stubs'); const runtime = join(dir, 'runtime')
      for (const folder of [home, stubs, runtime]) mkdirSync(folder)
      // A Mac's /etc/profile puts its own folders (/usr/local/bin) ahead of the PATH it was given, so a Node installed there
      // would be found by `command -v node` and the fallback never run: empty output on such a Mac. Git Bash on Windows has
      // no Node on its PATH, so the profile fixes PATH to the stubs, as it was before the login shell ran.
      writeFileSync(join(home, '.bash_profile'), `alias node='echo winpty-node'\nexport PATH='${stubs}'\n`)
      writeFileSync(join(runtime, 'node'), '#!/bin/sh\necho harness-node\n', { mode: 0o755 })
      writeFileSync(join(stubs, 'cygpath'), `#!/bin/sh\n[ "$1" = -u ] && [ "$2" = -- ] || exit 9\nprintf '%s\\n' "$3" > '${join(dir, 'asked')}'\nprintf '%s\\n' '${runtime}'\n`, { mode: 0o755 })
      const { args } = dshShellArgv('node', { platform: 'win32', gitBash: () => '/bin/bash' })
      const ran = spawnSync('/bin/bash', args, { cwd: dir, encoding: 'utf8', env: { HOME: home, PATH: stubs } })
      expect(ran.stdout).toBe('harness-node\n')
      expect(readFileSync(join(dir, 'asked'), 'utf8')).toBe(`${win32.dirname(managedNodePath())}\n`)
    })

    it('runs setup and doctor in the harness folder, though a login Git Bash goes home', async () => {
      // Git for Windows' /etc/profile changes to $HOME in a login shell unless CHERE_INVOKING is set; this profile
      // does the same, so the command would otherwise run in the home folder, not the harness's.
      const home = join(dir, 'home'); const stubs = join(dir, 'stubs'); const harness = join(dir, 'harness')
      for (const folder of [home, stubs, harness]) mkdirSync(folder)
      writeFileSync(join(home, '.bash_profile'), '[ -n "$CHERE_INVOKING" ] || cd "$HOME"\n')
      writeFileSync(join(stubs, 'cygpath'), `#!/bin/sh\nprintf '%s\\n' '${stubs}'\n`, { mode: 0o755 })
      const result = await runDshCommand('echo "ran in $(pwd)"', { cwd: harness, env: { HOME: home, PATH: stubs }, host: { platform: 'win32', gitBash: () => '/bin/bash' } })
      // Only the script's own line: this is a real login bash, and the host's /etc/profile says what it likes (Ubuntu's
      // CI runner: 'run-parts: command not found', with the PATH the test gives it).
      expect(result.lines.filter((line) => line.startsWith('ran in '))).toEqual([`ran in ${harness}`])
    })
  })
})

describe('dshShellAvailable', () => {
  it('is on wherever there is a shell for setup and doctor: a POSIX system, or Windows with Git Bash', () => {
    expect(dshShellAvailable({ platform: 'darwin' })).toBe(true)
    expect(dshShellAvailable({ platform: 'linux', gitBash: () => null })).toBe(true)
    expect(dshShellAvailable({ platform: 'win32', gitBash: () => 'C:\\Program Files\\Git\\bin\\bash.exe' })).toBe(true)
    expect(dshShellAvailable({ platform: 'win32', gitBash: () => null })).toBe(false)
  })
})

describe('dshNodeFallback', () => {
  let dir: string
  beforeEach(() => { seams.sh = true; dir = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-node-'))) })
  afterEach(() => { seams.sh = false; rmSync(dir, { recursive: true, force: true }) })

  it('puts the Node this daemon runs on at the END of a PATH that has no node', async () => {
    const result = await runDshCommand('echo "$PATH"; command -v node', { cwd: dir, env: { PATH: '/usr/bin:/bin' } })
    const runtimeBin = dirname(managedNodePath())
    expect(result.lines).toEqual([`/usr/bin:/bin:${runtimeBin}`, join(runtimeBin, 'node')])
  })

  it('leaves a PATH that already has a node alone', async () => {
    const own = join(dir, 'bin')
    mkdirSync(own)
    writeFileSync(join(own, 'node'), '#!/bin/sh\n', { mode: 0o755 })
    const result = await runDshCommand('echo "$PATH"; command -v node', { cwd: dir, env: { PATH: `${own}:/usr/bin:/bin` } })
    expect(result.lines).toEqual([`${own}:/usr/bin:/bin`, join(own, 'node')])
  })

  it('is one line, run before the command, that keeps an empty PATH from starting with a colon', () => {
    const line = dshNodeFallback()
    expect(line).toContain('"${PATH:+$PATH:}"\'')
    expect(line.startsWith('if ! command -v node >/dev/null 2>&1; then PATH=')).toBe(true)
  })
})

describe('isShellNoise', () => {
  it('drops only what zsh says about zle without a terminal', () => {
    expect(isShellNoise("zsh: can't change option: zle")).toBe(true)
    expect(isShellNoise("(eval):3: can't change option: zle")).toBe(true)
    expect(isShellNoise('ok   zle is a word a doctor might print')).toBe(false)
  })

  it('drops what bash says without a terminal, as Linux CI saw it', () => {
    expect(isShellNoise('bash: cannot set terminal process group (-1): Inappropriate ioctl for device')).toBe(true)
    expect(isShellNoise('bash: no job control in this shell')).toBe(true)
    expect(isShellNoise('/usr/bin/bash: no job control in this shell')).toBe(true)
    expect(isShellNoise('logout')).toBe(true)
    expect(isShellNoise('  ok   bash: no job control in this shell')).toBe(false)
    expect(isShellNoise('logout failed')).toBe(false)
  })

  it('keeps a line that names some other bash: only bash itself, or the paths it is installed at, says the notice', () => {
    // Review of #2025: any `<path>/bash: no job control in this shell` was dropped, a script's own line included.
    expect(isShellNoise('scripts/bash: no job control in this shell')).toBe(false)
    expect(isShellNoise('./bash: no job control in this shell')).toBe(false)
    expect(isShellNoise('/home/ana/project/bash: cannot set terminal process group (-1): Inappropriate ioctl for device')).toBe(false)
    expect(isShellNoise('mybash: no job control in this shell')).toBe(false)
    expect(isShellNoise('/bin/bash: cannot set terminal process group (4242): Inappropriate ioctl for device')).toBe(true)
  })
})

describe('runDshCommand', () => {
  let dir: string
  beforeEach(() => {
    seams.sh = true
    dir = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-shell-')))
  })
  afterEach(() => {
    seams.sh = false
    seams.fakeChild = null
    vi.useRealTimers()
    rmSync(dir, { recursive: true, force: true })
  })

  it('collects both streams line by line, in the cwd and env it was given, CRLF and partial lines included', async () => {
    const seen: string[] = []
    const result = await runDshCommand(
      `printf 'one\\r\\ntwo\\n'; echo "where $(basename "$PWD") $HARNESS_DSH" >&2; echo "zsh: can't change option: zle"; printf 'tail'`,
      { cwd: dir, env: { HARNESS_DSH: 'acme/thing' }, onLine: (line) => seen.push(line) },
    )
    expect(result.code).toBe(0)
    expect(result.signal).toBeNull()
    expect(result.timedOut).toBe(false)
    expect(result.lines).toEqual(expect.arrayContaining(['one', 'two', `where ${dir.split('/').pop()} acme/thing`, 'tail']))
    expect(result.lines).toHaveLength(4)
    expect(result.lines.indexOf('one')).toBeLessThan(result.lines.indexOf('two'))
    expect(result.lines.at(-1)).toBe('tail')
    expect(seen).toEqual(result.lines)
    // and with no env or onLine at all
    expect((await runDshCommand('exit 4', { cwd: dir })).code).toBe(4)
  })

  it('says how a command ended: its exit code, or the signal that ended it', async () => {
    expect(await runDshCommand('echo bye; exit 3', { cwd: dir })).toEqual({ code: 3, signal: null, lines: ['bye'], timedOut: false })
    const killed = await runDshCommand('kill -KILL $$', { cwd: dir })
    expect(killed).toMatchObject({ code: null, signal: 'SIGKILL', timedOut: false })
  })

  it('stops a command that outlives its timeout, and everything it started', async () => {
    const started = Date.now()
    const result = await runDshCommand('sleep 30 & echo started; wait', { cwd: dir, timeoutMs: 300 })
    expect(result.timedOut).toBe(true)
    expect(result.lines).toEqual(['started'])
    expect(Date.now() - started).toBeLessThan(10_000)
  })

  it('on Windows, ends the whole tree of a Git Bash run that outlives its timeout, not the shell alone', async () => {
    // Windows has no process groups: a signal to the group reached nothing, and the one to the shell ended Git Bash's
    // launcher alone, leaving what the doctor started running (review of #2025). Here a real bash stands in for Git
    // Bash, and the stand-in for the tree killer ends its group, as TerminateProcess down the tree does there.
    const ended: number[] = []
    const endTree = async (pid: number): Promise<void> => { ended.push(pid); process.kill(-pid, 'SIGKILL') }
    // The shell's pid is taken from the spawn, not from what the shell prints: a login bash reads the host's profile
    // first, and on the Linux runner that outlived the timeout, so the script never printed it (#2069 in CI). This
    // home's profile is as slow, so every host takes the same path.
    writeFileSync(join(dir, '.bash_profile'), 'sleep 5\n')
    seams.started = []
    const result = await runDshCommand('sleep 30 & wait', {
      cwd: dir, timeoutMs: 300, env: { HOME: dir, PATH: '/usr/bin:/bin' },
      host: { platform: 'win32', gitBash: () => '/bin/bash', endTree },
    })
    expect(result.timedOut).toBe(true)
    expect(seams.started).toHaveLength(1)
    expect(ended).toEqual(seams.started)
  })

  it('does not take the shell\'s report of the job its stop ended for the command\'s output', async () => {
    // The shell outlives its job here on purpose: it ignores SIGTERM, so it is in `wait` when the job the stop
    // ended dies, and reports it, as it did under load when the job's death reached it first.
    const report = '/bin/sh: line 1: 31849 Terminated: 15          sleep 30'
    const result = await runDshCommand(`echo started; trap 'echo "${report}" >&2; printf "${report}" >&2; exit 0' TERM; sleep 30 & wait`, { cwd: dir, timeoutMs: 300 })
    expect(result.timedOut).toBe(true)
    expect(result.lines).toEqual(['started'])
    // Before a stop, the same words are the command's own.
    expect((await runDshCommand(`echo "${report}"`, { cwd: dir })).lines).toEqual([report])
  })

  it('knows the shell\'s report of a job a signal ended, as bash words it on macOS and Linux', () => {
    expect(isKilledJobReport('/bin/sh: line 1: 31849 Terminated: 15          sleep 30')).toBe(true)
    expect(isKilledJobReport('bash: line 1: 10678 Terminated: 15          ( sleep 0.2; kill -TERM $$ )')).toBe(true)
    expect(isKilledJobReport('bash: line 1:  4242 Terminated              sleep 30')).toBe(true)
    expect(isKilledJobReport('bash: line 3: 86178 Killed: 9               sleep 30')).toBe(true)
    expect(isKilledJobReport('Terminated: 15')).toBe(false)
    expect(isKilledJobReport('sh: line 1: 12 Segmentation fault: 11  ./tool')).toBe(false)
    expect(isKilledJobReport('started')).toBe(false)
  })

  it('a command that cannot start is exit 127 with the reason as its one line, never a rejection', async () => {
    const missingCwd = await runDshCommand('true', { cwd: join(dir, 'missing') })
    expect(missingCwd.code).toBe(127)
    expect(missingCwd.lines).toEqual([expect.stringMatching(/^could not start: .*ENOENT/)])
    const seen: string[] = []
    const invalid = await runDshCommand('true', { cwd: 'nul\0byte', onLine: (line) => seen.push(line) })
    expect(invalid).toMatchObject({ code: 127, signal: null, timedOut: false })
    expect(invalid.lines).toEqual([expect.stringMatching(/^could not start: /)])
    expect(seen).toEqual(invalid.lines)
  })

  it('settles once when a child reports an error and an exit both, as Node warns it may', async () => {
    const child = Object.assign(new EventEmitter(), { pid: undefined, stdout: new EventEmitter(), stderr: new EventEmitter() }) as unknown as ChildProcess
    seams.fakeChild = () => child
    const seen: string[] = []
    const pending = runDshCommand('anything', { cwd: dir, onLine: (line) => seen.push(line) })
    child.stdout!.emit('data', Buffer.from('partial'))
    child.emit('error', new Error('spawn EACCES'))
    child.emit('exit', 1, null)
    const result = await pending
    expect(result).toEqual({ code: 127, signal: null, lines: ['could not start: spawn EACCES', 'partial'], timedOut: false })
    expect(seen).toEqual(['could not start: spawn EACCES', 'partial'])
  })
})

describe('spawnDshCommand and killProcessGroup', () => {
  let dir: string
  beforeEach(() => {
    seams.sh = true
    dir = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-kill-')))
  })
  afterEach(() => {
    seams.sh = false
    rmSync(dir, { recursive: true, force: true })
  })

  const exited = (child: ChildProcess): Promise<[number | null, NodeJS.Signals | null]> =>
    new Promise((resolve) => child.once('exit', (code, signal) => resolve([code, signal])))

  // Process groups are POSIX: on Windows the command is spawned without `detached` (ownProcessGroup, docs/windows-rules.md), and
  // its tree is ended at once with no SIGTERM and no grace, which 'on Windows, ends the whole tree…' above covers (#4184).
  it.skipIf(process.platform === 'win32')('SIGTERMs the whole group, and SIGKILLs what ignores it once the grace is over', async () => {
    const polite = spawnDshCommand('sleep 30', { cwd: dir })
    await new Promise((resolve) => setTimeout(resolve, 100))
    const politeExit = exited(polite)
    killProcessGroup(polite, 5_000)
    expect(await politeExit).toEqual([null, 'SIGTERM'])

    const stubborn = spawnDshCommand(`trap '' TERM; echo ready; sleep 30`, { cwd: dir })
    await new Promise<void>((resolve) => stubborn.stdout!.once('data', () => resolve()))
    const stubbornExit = exited(stubborn)
    const started = Date.now()
    killProcessGroup(stubborn, 200)
    expect(await stubbornExit).toEqual([null, 'SIGKILL'])
    expect(Date.now() - started).toBeGreaterThanOrEqual(150)
  })

  it('does nothing without a pid, and nothing harmful for a process already gone', async () => {
    killProcessGroup(Object.assign(new EventEmitter(), { pid: undefined }) as unknown as ChildProcess)
    const gone = spawnDshCommand('exit 0', { cwd: dir })
    await exited(gone)
    expect(() => killProcessGroup(gone, 20)).not.toThrow()
    // the SIGKILL that follows the grace finds nothing either
    await new Promise((resolve) => setTimeout(resolve, 60))
  })
})