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.

9.0 KB
Raw Blame
/**
 * The terminal on the tmux a distribution ships. Debian 10 ships 2.8, Ubuntu 20.04 3.0a, Debian 11 3.1c:
 * before 3.2 the control client's `-f ignore-size` was a usage error and no terminal opened at all;
 * before 3.1 `capture-pane -N` failed every snapshot; before 3.0 `send-keys -H` failed every keystroke;
 * before 2.9 there was no `resize-window`. Each is asked of the tmux by name (`tmuxVersion.ts`), and
 * the same stream is proven against real tmux 2.8 and 3.0a in tmuxStream.real.spec.ts.
 */
import { EventEmitter } from 'node:events'
import { PassThrough, Writable } from 'node:stream'
import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { tmuxControlGate } from './tmuxControlGate.js'
import { TmuxControlStream } from './tmuxStream.js'
import { assumeTmuxVersion, resetTmuxVersionCache, type TmuxVersion } from './tmuxVersion.js'

vi.mock('node:child_process', async (importOriginal) => ({
  ...await importOriginal<typeof import('node:child_process')>(),
  execFile: vi.fn(),
  spawn: vi.fn(),
}))

afterEach(() => {
  vi.resetAllMocks()
  resetTmuxVersionCache()
})

/** A control client that answers every command, `display-message` with [meta], and records what it was sent. */
function controlClient(version: TmuxVersion, meta = '$1|@1|1|80|24|80|24|0|0|0|1|0|0|0|0|0', answersAttach = true) {
  assumeTmuxVersion(version)
  const sent: string[] = []
  const child = new EventEmitter() as {
    -readonly [K in keyof ChildProcessWithoutNullStreams]: ChildProcessWithoutNullStreams[K]
  }
  child.stdout = new PassThrough()
  child.stderr = new PassThrough()
  child.exitCode = null
  child.signalCode = null
  let command = 1
  child.kill = () => { child.exitCode = 0; child.emit('close', 0); return true }
  child.stdin = new Writable({
    write(chunk, _encoding, callback) {
      // One write may carry several commands (`runTogether`): tmux answers each, in order.
      const lines = chunk.toString().split('\n').filter((line: string) => line.length > 0)
      sent.push(...lines)
      const numbers = lines.map(() => command++)
      setImmediate(() => {
        callback()
        lines.forEach((line: string, index: number) => {
          if (line.startsWith('detach-client')) { child.kill(); return }
          const body = line.startsWith('display-message') ? `${meta}\n` : ''
          child.stdout.emit('data', Buffer.from(`%begin 1 ${numbers[index]} 0\n${body}%end 1 ${numbers[index]} 0\n`))
        })
      })
    },
  })
  vi.mocked(execFile).mockImplementation(((...args: unknown[]) => {
    (args.at(-1) as (error: null, stdout: Buffer) => void)(null, Buffer.from(`${meta}\n`))
    return child
  }) as typeof execFile)
  vi.mocked(spawn).mockImplementation(() => {
    setImmediate(() => {
      child.emit('spawn')
      if (answersAttach) setImmediate(() => child.stdout.emit('data', Buffer.from('%begin 1 0 0\n%end 1 0 0\n')))
    })
    return child
  })
  return { sent }
}

async function open(size = { cols: 80, rows: 24 }, readOnly = false) {
  const opened = await TmuxControlStream.open('%1', size, { onData: () => {}, onClose: () => {} }, readOnly)
  expect(opened.state).toBe('succeeded')
  if (opened.state !== 'succeeded') throw new Error('stream did not open')
  return opened.value
}

describe('the terminal on an older tmux', () => {
  it.each([
    [{ major: 3, minor: 2 }, ['-C', 'attach-session', '-f', 'ignore-size', '-t', '%1']],
    // Before client flags the control client never sets a size of its own, and counts for none.
    [{ major: 3, minor: 1 }, ['-C', 'attach-session', '-t', '%1']],
    [{ major: 2, minor: 8 }, ['-C', 'attach-session', '-t', '%1']],
  ])('attaches its control client as tmux %o takes it', async (version, argv) => {
    controlClient(version)
    const stream = await open()
    expect(vi.mocked(spawn).mock.calls[0]?.[1]).toEqual(argv)
    await stream.close()
  })

  it('types through send-keys -H from 3.0, and as literal text and keys before it', async () => {
    const modern = controlClient({ major: 3, minor: 0 })
    let stream = await open()
    expect((await stream.writeRaw(Buffer.from("ls;\n"))).state).toBe('succeeded')
    expect(modern.sent.slice(-1)).toEqual(['send-keys -t %1 -H 6c 73 3b 0a'])
    await stream.close()

    vi.resetAllMocks()
    const old = controlClient({ major: 2, minor: 8 })
    stream = await open()
    expect((await stream.writeRaw(Buffer.from("echo 'hi';\n-x"))).state).toBe('succeeded')
    expect(old.sent.slice(-3)).toEqual([
      `send-keys -t %1 -l -- 'echo '"'"'hi'"'"'\\;'`,
      'send-keys -t %1 C-j',
      `send-keys -t %1 -l -- '-x'`,
    ])
    await stream.close()
  })

  it('sizes its window with resize-window from 2.9, and as a control client before it, never under 2x2', async () => {
    const modern = controlClient({ major: 2, minor: 9 })
    let stream = await open({ cols: 100, rows: 30 })
    expect(modern.sent).toContain('resize-window -t @1 -x 100 -y 30')
    await stream.close()

    vi.resetAllMocks()
    const old = controlClient({ major: 2, minor: 8 })
    stream = await open({ cols: 100, rows: 30 })
    expect((await stream.resize({ cols: 1, rows: 1 })).state).toBe('succeeded')
    expect(old.sent.filter((line) => /resize|refresh/.test(line))).toEqual(['refresh-client -C 100,30', 'refresh-client -C 2,2'])
    await stream.close()
  })

  it('keeps a row\'s trailing blanks from 3.1, and captures without asking for them before it', async () => {
    for (const [version, flag] of [[{ major: 3, minor: 1 }, ' -N'], [{ major: 3, minor: 0 }, '']] as const) {
      vi.resetAllMocks()
      const client = controlClient(version)
      const stream = await open()
      stream.beginSnapshot()
      expect((await stream.snapshot()).state).toBe('succeeded')
      stream.endSnapshot()
      expect(client.sent.filter((line) => line.startsWith('capture-pane'))).toEqual([
        `capture-pane -p -e${flag} -t %1 -S -500 -E -1`,
        `capture-pane -p -e${flag} -t %1`,
      ])
      await stream.close()
    }
  })
})

describe('a terminal on a tmux that crashes when one attaches as another goes (tmuxControlGate.ts)', () => {
  const tick = () => new Promise((resolve) => setImmediate(resolve))
  const empty = { room: null, inside: 0, waiting: 0 }
  afterEach(() => { vi.useRealTimers() })

  it('attaches in the attach room until tmux answers, and goes in the other, asking tmux once more before it leaves', async () => {
    const client = controlClient({ major: 3, minor: 4 })
    const atSpawn: unknown[] = []
    const attach = vi.mocked(spawn).getMockImplementation()!
    vi.mocked(spawn).mockImplementation(((...args: Parameters<typeof spawn>) => {
      atSpawn.push(tmuxControlGate.state)
      return attach(...args)
    }) as typeof spawn)
    const stream = await open()
    await stream.attached
    expect(atSpawn).toEqual([{ room: 'attach', inside: 1, waiting: 0 }])
    expect(tmuxControlGate.state).toEqual(empty)

    // Another terminal attaching: this one's `detach-client` waits for it.
    const attaching = await tmuxControlGate.enter('attach')
    vi.mocked(execFile).mockClear()
    const closing = stream.close()
    await tick()
    expect(client.sent).not.toContain('detach-client')
    attaching()
    await closing
    expect(client.sent.at(-1)).toBe('detach-client')
    // tmux tells the others it went only once it reads the socket close: one more answer comes after that.
    expect(vi.mocked(execFile).mock.calls.map((call) => call[1])).toEqual([['display-message', '-p', '#{pid}']])
    expect(tmuxControlGate.state).toEqual(empty)
  })

  it('on tmux 3.7 neither waits nor asks again', async () => {
    const client = controlClient({ major: 3, minor: 7 })
    const stream = await open()
    const attaching = await tmuxControlGate.enter('attach')
    vi.mocked(execFile).mockClear()
    try {
      await stream.close()
      expect(client.sent.at(-1)).toBe('detach-client')
      expect(vi.mocked(execFile)).not.toHaveBeenCalled()
    } finally {
      attaching()
    }
  })

  it('leaves the attach room when its client cannot start', async () => {
    controlClient({ major: 3, minor: 4 })
    vi.mocked(spawn).mockImplementation((() => {
      const child = new EventEmitter()
      setImmediate(() => child.emit('error', new Error('spawn tmux ENOENT')))
      return child
    }) as unknown as typeof spawn)
    const opened = await TmuxControlStream.open('%1', { cols: 80, rows: 24 }, { onData: () => {}, onClose: () => {} })
    expect(opened).toEqual({ state: 'failed', reason: 'tmux control client could not start' })
    expect(tmuxControlGate.state).toEqual(empty)
  })

  it('keeps the others waiting no longer than its first command may take, when tmux never answers its attach', async () => {
    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
    controlClient({ major: 3, minor: 4 }, undefined, false)
    const watching = await open(undefined, true)
    expect(tmuxControlGate.state).toEqual({ room: 'attach', inside: 1, waiting: 0 })
    vi.advanceTimersByTime(3_000)
    expect(tmuxControlGate.state).toEqual(empty)
    await watching.close()
    expect(tmuxControlGate.state).toEqual(empty)
  })
})