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 { spawn } from 'node:child_process'
import { copyFileSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { afterEach, describe, expect, it, vi } from 'vitest'
import {
  createWindowsDialWatch, harnessSerialBinary, openWindowsPort, parseSerialState, windowsPortInUse,
  type CommandFor, type WindowsDialWatch,
} from './windowsSerial.js'

const FAKE = fileURLToPath(new URL('./__fixtures__/fakeHarnessSerial.mjs', import.meta.url))
const fake: CommandFor = (args) => ({ file: process.execPath, args: [FAKE, ...args] })
const line = (value: unknown) => JSON.stringify(value)
const until = async (check: () => boolean, ms = 3_000) => {
  const end = Date.now() + ms
  while (!check()) {
    if (Date.now() > end) throw new Error('timed out')
    await new Promise((resolve) => setTimeout(resolve, 20))
  }
}
const eventually = async <T>(read: () => Promise<T>, ok: (value: T) => boolean, ms = 3_000): Promise<T> => {
  const end = Date.now() + ms
  for (;;) {
    const value = await read()
    if (ok(value)) return value
    if (Date.now() > end) throw new Error(`timed out; last ${JSON.stringify(value)}`)
    await new Promise((resolve) => setTimeout(resolve, 20))
  }
}

const roots: string[] = []
const children: ReturnType<typeof spawn>[] = []
const trackedSpawn: typeof spawn = ((...args: Parameters<typeof spawn>) => {
  const child = spawn(...args)
  children.push(child)
  return child
}) as typeof spawn
const alive = (pid: number | undefined) => { if (!pid) return false; try { process.kill(pid, 0); return true } catch { return false } }
let watches: WindowsDialWatch[] = []
afterEach(async () => {
  for (const watch of watches.splice(0)) watch.stop()
  for (const child of children.splice(0)) {
    if (alive(child.pid)) child.kill('SIGKILL')
    child.stdin?.destroy()
    child.stdout?.destroy()
    child.stderr?.destroy()
    await until(() => !alive(child.pid), 1_000)
  }
  // Windows holds a program's file for a moment after it exits (EBUSY on the Arm runner).
  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 })
  vi.unstubAllEnvs()
})
const watchWith = (lines: string[], extra: Record<string, string> = {}, deps: Partial<Parameters<typeof createWindowsDialWatch>[0]> = {}) => {
  vi.stubEnv('FAKE_SERIAL_LINES', JSON.stringify(lines))
  for (const [name, value] of Object.entries(extra)) vi.stubEnv(name, value)
  const log = vi.fn()
  const watch = createWindowsDialWatch({ command: fake, log, spawn: trackedSpawn, ...deps })
  watches.push(watch)
  return { watch, log }
}

describe('finding harness-serial.exe', () => {
  const runtime = (name: string) => {
    const tmp = mkdtempSync(join(tmpdir(), 'serial-bin-'))
    roots.push(tmp)
    const root = join(tmp, name)
    mkdirSync(join(root, 'pty', '0.4.21'), { recursive: true })
    writeFileSync(join(root, 'pty', 'current-pty'), '0.4.21\n')
    return root
  }

  it('takes HARNESS_SERIAL_BIN as it is, then the installed host version, then the bundle', () => {
    const root = runtime('runtime')
    const installed = join(root, 'pty', '0.4.21', 'harness-serial.exe')
    const beside = join('/bundle', 'pty', 'harness-serial.exe')
    const exists = (file: string) => file === installed || file === beside
    expect(harnessSerialBinary({ env: { HARNESS_SERIAL_BIN: ' C:\\x\\harness-serial.exe ' }, runtimeDir: root, exists })).toBe('C:\\x\\harness-serial.exe')
    expect(harnessSerialBinary({ env: {}, runtimeDir: root, besideDir: '/bundle', exists })).toBe(installed)
    expect(harnessSerialBinary({ env: {}, runtimeDir: root, besideDir: '/bundle', exists: (file) => file === beside })).toBe(beside)
    expect(harnessSerialBinary({ env: {}, runtimeDir: root, besideDir: '/bundle', exists: () => false })).toBeNull()
  })

  // Review Focus 1: a profile whose name has spaces, an apostrophe, & and % and is not ASCII.
  it('finds it under a profile path a shell would mangle', () => {
    const root = runtime("Nguyễn Văn A' & 100%")
    const installed = join(root, 'pty', '0.4.21', 'harness-serial.exe')
    expect(harnessSerialBinary({ env: {}, runtimeDir: root, exists: (file) => file === installed })).toBe(installed)
  })
})

describe('the watch line', () => {
  it('takes COM ports with the dial ids, and drops what is not a port', () => {
    expect(parseSerialState(line({ console: true, ports: [
      { path: 'COM9', serialNumber: '28:84:85:00:00:01', session: '133' },
      { path: 'COM10' },
      { path: 'NUL' }, { serialNumber: 'x' }, null,
    ] }))).toEqual({ console: true, ports: [
      { path: 'COM9', vendorId: 0x303a, productId: 0x1001, serialNumber: '28:84:85:00:00:01', session: '133' },
      { path: 'COM10', vendorId: 0x303a, productId: 0x1001 },
    ] })
    for (const bad of ['', 'not json', '{"ports":[]}', '{"console":"yes","ports":[]}', '{"console":true}', '[]']) {
      expect(parseSerialState(bad)).toBeNull()
    }
  })
})

describe('the daemon\'s watch', () => {
  it('spawns only on the first getter, fails closed, and discovers a late state after the first read deadline', async () => {
    const { watch } = watchWith([line({ console: false, ports: [{ path: 'COM17' }] })], { FAKE_SERIAL_DELAY: '180' }, { firstLineMs: 30 })
    expect(children).toHaveLength(0)
    expect(watch.console()).toBe(false)
    expect(children).toHaveLength(1)
    expect(await watch.ports()).toEqual([])
    expect(watch.console()).toBe(false)
    expect((await eventually(() => watch.ports(), ports => ports.length > 0))[0]?.path).toBe('COM17')
    expect(watch.console()).toBe(false)
  })

  it('bounds an unresponsive watch first read once and kills a watch that ignores stdin EOF on stop', async () => {
    const { watch } = watchWith([], { FAKE_SERIAL_STUBBORN: '1' }, { firstLineMs: 35 })
    expect(await watch.ports()).toEqual([])
    const start = performance.now()
    expect(await watch.ports()).toEqual([])
    expect(performance.now() - start).toBeLessThan(25)
    const pid = children.at(-1)!.pid
    watch.stop()
    await until(() => !alive(pid), 3_000)
  })

  it('wakes a waiting caller on stop and ignores a delayed state from its old process', async () => {
    const { watch } = watchWith([line({ console: true, ports: [{ path: 'COM3' }] })], { FAKE_SERIAL_DELAY: '100' })
    const ports = watch.ports()
    watch.stop()
    expect(await ports).toEqual([])
    await new Promise(resolve => setTimeout(resolve, 150))
    expect(watch.console()).toBe(false)
  })

  it('reports a failed spawn once, stays fail closed, and can recover on a later scan', async () => {
    let clock = 0
    let missing = true
    const command: CommandFor = args => missing ? { file: '/missing/harness-serial.exe', args } : fake(args)
    const { watch, log } = watchWith([line({ console: true, ports: [{ path: 'COM3' }] })], {}, { command, now: () => clock })
    expect(await watch.ports()).toEqual([])
    expect(watch.console()).toBe(false)
    expect(log).toHaveBeenCalledTimes(1)
    missing = false
    clock = 5_000
    expect((await watch.ports())[0]?.path).toBe('COM3')
    expect(watch.console()).toBe(true)
  })

  it('treats an invalid executable argument as an unavailable watch without throwing from either getter', async () => {
    const { watch, log } = watchWith([], {}, { command: args => ({ file: '\0', args }) })
    expect(watch.console()).toBe(false)
    expect(await watch.ports()).toEqual([])
    expect(log).toHaveBeenCalledTimes(1)
  })

  it('waits for the first line, then serves the dials and whether this user is at the screen', async () => {
    // Review Focus 5: two dials at once.
    const { watch } = watchWith([line({ console: false, ports: [{ path: 'COM9', serialNumber: 'AA' }, { path: 'COM10', serialNumber: 'BB' }] })])
    expect(watch.console()).toBe(false) // An unknown console is fail closed; the getter still starts discovery.
    const ports = await watch.ports()
    expect(ports.map((port) => port.path)).toEqual(['COM9', 'COM10'])
    expect(watch.console()).toBe(false)
  })

  // Review Focus 4. The junk line comes first, so the first answer waits for the real one.
  it('reads a line split across two writes, and skips a line that is not a state', async () => {
    const { watch } = watchWith(['harness-serial 0.1.0 starting', line({ console: true, ports: [{ path: 'COM3' }] })], { FAKE_SERIAL_SPLIT: '1' })
    expect((await watch.ports()).map((port) => port.path)).toEqual(['COM3'])
  })

  it('follows the newest line', async () => {
    const { watch } = watchWith([line({ console: true, ports: [{ path: 'COM3' }] }), line({ console: true, ports: [] })])
    expect((await watch.ports()).map((port) => port.path)).toEqual(['COM3'])
    expect(await eventually(() => watch.ports(), (ports) => ports.length === 0)).toEqual([])
  })

  it('forgets the dials when the watch ends, says why once, and starts it again no sooner than 5 s', async () => {
    let clock = 0
    const command = vi.fn(fake)
    const { watch, log } = watchWith([line({ console: true, ports: [{ path: 'COM3' }] })], { FAKE_SERIAL_EXIT: '2' }, { command, now: () => clock })
    expect((await watch.ports()).map((port) => port.path)).toEqual(['COM3'])
    await until(() => log.mock.calls.some(([text]) => String(text).includes('error: enumeration failed')))
    expect(await watch.ports()).toEqual([])
    expect(watch.console()).toBe(false)
    expect(command).toHaveBeenCalledTimes(1)
    clock = 4_999
    await watch.ports()
    expect(command).toHaveBeenCalledTimes(1)
    clock = 5_000
    await watch.ports()
    expect(command).toHaveBeenCalledTimes(2)
  })

  it('says once that harness-serial is not installed, and finds no dial', async () => {
    let clock = 0
    const log = vi.fn()
    const watch = createWindowsDialWatch({ command: () => null, log, now: () => clock })
    for (let i = 0; i < 3; i++) { clock += 10_000; expect(await watch.ports()).toEqual([]) }
    expect(log).toHaveBeenCalledTimes(1)
    expect(log.mock.calls[0]![0]).toContain('harness-serial is not installed')
  })

  // Review Focus 3: the daemon killed outright. Its watch must end with it, or it would outlive every daemon.
  it.each(['watch', 'open'])('ends its %s with a parent that is killed, because the pipe closes', async (mode) => {
    const parent = spawn(process.execPath, ['-e', `
      const { spawn } = require('node:child_process')
      const child = spawn(process.execPath, [${JSON.stringify(FAKE)}, ${JSON.stringify(mode)}, 'COM3'], { stdio: ['pipe', 'ignore', 'ignore'] })
      console.log(child.pid)
      setInterval(() => {}, 1000)
    `], { stdio: ['ignore', 'pipe', 'inherit'] })
    const pid = Number(await new Promise<string>((resolve) => parent.stdout.once('data', (chunk) => resolve(String(chunk)))))
    parent.kill('SIGKILL')
    const alive = () => { try { process.kill(pid, 0); return true } catch { return false } }
    await until(() => !alive(), 5_000)
  })

  it('lets a parent using the real bridge exit naturally and takes the watch with it', async () => {
    const source = new URL('./windowsSerial.ts', import.meta.url).href
    const parent = spawn(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', `
      import { spawn } from 'node:child_process'
      const { createWindowsDialWatch } = await import(${JSON.stringify(source)})
      const watch = createWindowsDialWatch({
        command: args => ({ file: process.execPath, args: [${JSON.stringify(FAKE)}, ...args] }),
        spawn: (...args) => { const child = spawn(...args); console.log(child.pid); return child },
      })
      watch.console()
    `], { stdio: ['ignore', 'pipe', 'inherit'] })
    children.push(parent)
    const pid = Number(await new Promise<string>((resolve) => parent.stdout.once('data', chunk => resolve(String(chunk)))))
    await until(() => !alive(parent.pid), 3_000)
    await until(() => !alive(pid), 3_000)
  })
})

describe('the link to one dial', () => {
  it('starts from an executable and fixture path containing shell metacharacters and non-ASCII letters', async () => {
    const root = mkdtempSync(join(tmpdir(), "Nguyễn Văn A' & 100%-"))
    roots.push(root)
    const executable = join(root, 'harness-serial.exe')
    // Windows symlinks can require privileges; a copied executable exercises the same shell-free path there.
    if (process.platform === 'win32') copyFileSync(process.execPath, executable)
    else symlinkSync(process.execPath, executable)
    const fixture = join(root, 'fake serial.mjs')
    copyFileSync(FAKE, fixture)
    const stream = await openWindowsPort({ file: executable, args: [fixture, 'open', 'COM17'] }, { spawn: trackedSpawn })
    const response = new Promise<Buffer>(resolve => stream.once('data', resolve))
    stream.write(Buffer.from('exact bytes'))
    expect(await response).toEqual(Buffer.from('exact bytes'))
    const closed = new Promise(resolve => stream.once('close', resolve))
    const pid = children.at(-1)!.pid
    stream.destroy()
    await closed
    expect(alive(pid)).toBe(false)
  })

  it('requires a complete open line and kills an unresponsive child within the close deadline', async () => {
    vi.stubEnv('FAKE_SERIAL_OPEN', 'partial')
    await expect(openWindowsPort(fake(['open', 'COM3'])!, { spawn: trackedSpawn, openWaitMs: 120, closeWaitMs: 50 })).rejects.toMatchObject({ code: 'ETIMEDOUT' })
    await until(() => !alive(children.at(-1)!.pid))
    vi.stubEnv('FAKE_SERIAL_OPEN', 'stubborn')
    await expect(openWindowsPort(fake(['open', 'COM3'])!, { spawn: trackedSpawn, openWaitMs: 120, closeWaitMs: 50 })).rejects.toMatchObject({ code: 'ETIMEDOUT' })
    await until(() => !alive(children.at(-1)!.pid))
  })

  it('rejects startup failures with EIO and no orphan child', async () => {
    await expect(openWindowsPort({ file: '/missing/harness-serial.exe', args: [] }, { spawn: trackedSpawn })).rejects.toMatchObject({ code: 'EIO' })
    vi.stubEnv('FAKE_SERIAL_OPEN', 'unknown-failure')
    await expect(openWindowsPort({ file: process.execPath, args: [FAKE, 'invalid'] }, { spawn: trackedSpawn })).rejects.toMatchObject({ code: 'EIO' })
  })

  it('kills an opened child that ignores stdin EOF before reporting close', async () => {
    vi.stubEnv('FAKE_SERIAL_OPEN', 'stubborn-open')
    const stream = await openWindowsPort(fake(['open', 'COM3'])!, { spawn: trackedSpawn, closeWaitMs: 60 })
    const child = children.at(-1)!
    const closed = new Promise(resolve => stream.once('close', resolve))
    stream.destroy()
    await closed
    expect(alive(child.pid)).toBe(false)
    expect(child.signalCode).toBe('SIGKILL')
    expect(child.exitCode).not.toBe(0)
  })

  it('closes a backpressured child and all owned pipes without consuming the readable stream', async () => {
    const stream = await openWindowsPort({ file: process.execPath, args: ['-e', `
      process.stderr.write('open\\n')
      process.stdout.write(Buffer.alloc(256 * 1024, 7))
      process.stdin.resume()
      process.stdin.on('end', () => process.exit(0))
    `] }, { spawn: trackedSpawn, closeWaitMs: 60 })
    const child = children.at(-1)!
    // Wait for real readable backpressure, rather than assuming the child has produced its bytes.
    await until(() => stream.readableLength >= stream.readableHighWaterMark)
    expect(child.stdout?.isPaused()).toBe(true)
    let closed = false
    stream.once('close', () => { closed = true })
    stream.destroy()
    await until(() => closed, 400)
    expect(alive(child.pid)).toBe(false)
    expect(child.stdin?.destroyed).toBe(true)
    expect(child.stdout?.destroyed).toBe(true)
    expect(child.stderr?.destroyed).toBe(true)
  })

  it('closes stdin on writable EOF and waits for the child to release the port', async () => {
    const stream = await openWindowsPort(fake(['open', 'COM3'])!, { spawn: trackedSpawn })
    const pid = children.at(-1)!.pid
    const error = vi.fn()
    stream.on('error', error)
    const closed = new Promise(resolve => stream.once('close', resolve))
    stream.end(Buffer.from('last bytes'))
    stream.resume()
    await closed
    expect(error).not.toHaveBeenCalled()
    expect(alive(pid)).toBe(false)
  })

  it('carries bytes both ways, a frame larger than one pipe write included, and ends its child on close', async () => {
    const stream = await openWindowsPort(fake(['open', 'COM3'])!)
    const received: Buffer[] = []
    stream.on('data', (chunk: Buffer) => received.push(chunk))
    const big = Buffer.alloc(100_000, 7)
    await new Promise<void>((resolve, reject) => stream.write(Buffer.from([0, 255, 13, 10]), (error) => error ? reject(error) : resolve()))
    await new Promise<void>((resolve, reject) => stream.write(big, (error) => error ? reject(error) : resolve()))
    await until(() => Buffer.concat(received).length === 4 + big.length)
    expect(Buffer.concat(received)).toEqual(Buffer.concat([Buffer.from([0, 255, 13, 10]), big]))
    const closed = new Promise((resolve) => stream.once('close', resolve))
    stream.destroy()
    await closed
  })

  it('refuses a port another program has, one that is gone, and one that never says open', async () => {
    vi.stubEnv('FAKE_SERIAL_OPEN', 'busy')
    await expect(openWindowsPort(fake(['open', 'COM3'])!)).rejects.toMatchObject({ code: 'EBUSY' })
    vi.stubEnv('FAKE_SERIAL_OPEN', 'gone')
    await expect(openWindowsPort(fake(['open', 'COM3'])!)).rejects.toMatchObject({ code: 'ENOENT' })
    vi.stubEnv('FAKE_SERIAL_OPEN', 'silent')
    await expect(openWindowsPort(fake(['open', 'COM3'])!, { openWaitMs: 300 })).rejects.toMatchObject({ code: 'ETIMEDOUT' })
  })

  it('fails with the reason harness-serial gave when the dial is unplugged', async () => {
    vi.stubEnv('FAKE_SERIAL_OPEN', 'unplug:100')
    const stream = await openWindowsPort(fake(['open', 'COM3'])!)
    const events: string[] = []
    stream.on('end', () => events.push('end'))
    stream.on('error', () => events.push('error'))
    stream.resume()
    // Both listeners first: 'close' follows 'error' at once.
    const closed = new Promise((resolve) => stream.once('close', resolve))
    const error = await new Promise<NodeJS.ErrnoException>((resolve) => stream.once('error', resolve))
    expect(error.code).toBe('closed: The device is not connected.')
    await closed
    expect(events[0]).toBe('error')
  })
})

describe('is another program holding the port', () => {
  it('treats an invalid executable argument as cannot tell', async () => {
    expect(await windowsPortInUse('COM3', args => ({ file: '\0', args }))).toBe(false)
  })
  it('is busy only when harness-serial says busy; cannot tell reads as free', async () => {
    for (const [probe, held] of [['busy', true], ['free', false], ['gone', false]] as const) {
      vi.stubEnv('FAKE_SERIAL_PROBE', probe)
      expect(await windowsPortInUse('COM3', fake)).toBe(held)
    }
    expect(await windowsPortInUse('COM3', () => null)).toBe(false)
  })
})