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.

19.0 KB
Raw Blame
import { execFileSync } from 'child_process'
import { chmodSync, existsSync, realpathSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs'
import { tmpdir } from 'os'
import { join } from 'path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { PTY_PROTOCOL } from '../ptyHost/protocol.js'
import { DigestMismatchError } from '../selfUpdate.js'
import {
  PTY_PAYLOAD_FILES, PtyPayloadRefused, PtyPayloadUnpackFailed, CANARY_HOME_STALE_MS, SERVE_CANARY_BOUND_MS, fetchPtyEntry, preparePtyPayload, ptyManifestUrl, ptyPlatformKey,
  probeVersionLine, processesInFolder, ptyUpdateWanted, serveCanary, sweepCanaryHomes, sweepStagingFolders, type PtyEntry,
} from './ptyPayload.js'

let tmp: string
beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), 'pty-payload-')) })
afterEach(() => { vi.useRealTimers(); rmSync(tmp, { recursive: true, force: true }) })

function zipOf(names: readonly string[]): Buffer {
  const src = join(tmp, 'src'); rmSync(src, { recursive: true, force: true }); mkdirSync(src)
  for (const n of names) writeFileSync(join(src, n), n)
  const out = join(tmp, 'p.zip'); rmSync(out, { force: true })
  // Windows has no `zip`: its own bsdtar writes one (`-a` picks the format from the .zip suffix), and the payload's
  // default unzip there is that same tar.exe, so these cases go through the real Windows unpack.
  if (process.platform === 'win32') {
    execFileSync(join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe'), ['-a', '-c', '-f', out, ...names], { cwd: src, windowsHide: true })
  } else {
    execFileSync('zip', ['-q', '-j', out, ...names.map((n) => join(src, n))])
  }
  return readFileSync(out)
}

const entry: PtyEntry = { version: '0.11.0', url: 'https://cdn.example/p.zip', sha256: 'a'.repeat(64), size: 10 }
const goodProbe = (host: object = {}, serial: object = {}) => async (bin: string) =>
  bin.endsWith('harness-pty.exe')
    ? { version: '0.11.0', protocol: 2, features: ['seed'], ...host }
    : { version: '0.11.0', ...serial }
const run = (deps: Parameters<typeof preparePtyPayload>[2], files: readonly string[] = PTY_PAYLOAD_FILES) =>
  preparePtyPayload(entry, tmp + '/rt', { download: async () => zipOf(files), probe: goodProbe(), serve: async () => {}, ...deps })
const leftovers = () => (existsSync(join(tmp, 'rt', 'pty')) ? readdirSync(join(tmp, 'rt', 'pty')) : [])

describe('ptyManifestUrl', () => {
  it('swaps the last two segments', () => {
    expect(ptyManifestUrl('https://x.example/a/cli/metadata.json')).toBe('https://x.example/a/pty/metadata.json')
  })
  it('throws on any other url', () => {
    expect(() => ptyManifestUrl('https://x.example/a/other.json')).toThrow()
  })
})

describe('ptyPlatformKey', () => {
  it('maps x64 and arm64, and nothing else', () => {
    expect(ptyPlatformKey('x64')).toBe('win32-x64')
    expect(ptyPlatformKey('arm64')).toBe('win32-arm64')
    expect(ptyPlatformKey('ia32')).toBeNull()
  })
})

describe('ptyUpdateWanted', () => {
  const cli = '1.2.3'
  it('newer is wanted', () => expect(ptyUpdateWanted(entry, { pty: '0.10.0', cli }, [])).toBe(true))
  it('same and older are not', () => {
    expect(ptyUpdateWanted(entry, { pty: '0.11.0', cli }, [])).toBe(false)
    expect(ptyUpdateWanted(entry, { pty: '0.12.0', cli }, [])).toBe(false)
  })
  it('a dev CLI never updates', () => expect(ptyUpdateWanted(entry, { pty: '0.10.0', cli: '1.2.3-dev.abc' }, [])).toBe(false))
  it('a rejected version is not', () => expect(ptyUpdateWanted(entry, { pty: '0.10.0', cli }, ['0.11.0'])).toBe(false))
  // Without a current-pty there is no previous version for probation to roll back to (install.ps1 installs the first).
  it('no installed pty wants none', () => expect(ptyUpdateWanted(entry, { pty: null, cli }, [])).toBe(false))
})

describe('preparePtyPayload', () => {
  it('a good zip is unpacked into a staging folder', async () => {
    const p = await run({})
    expect(p).toMatchObject({ version: '0.11.0', protocol: 2, features: ['seed'] })
    expect(p.staging.startsWith(join(tmp, 'rt', 'pty', '.staging-'))).toBe(true)
    expect(readdirSync(p.staging).sort()).toEqual([...PTY_PAYLOAD_FILES].sort())
  })
  it('a digest mismatch is refused and leaves nothing', async () => {
    await expect(run({ download: async () => { throw new DigestMismatchError('bad') } })).rejects.toBeInstanceOf(PtyPayloadRefused)
    expect(leftovers()).toEqual([])
  })
  it('a missing or extra file is refused', async () => {
    await expect(run({}, PTY_PAYLOAD_FILES.slice(1))).rejects.toThrow(/expected/)
    await expect(run({}, [...PTY_PAYLOAD_FILES, 'extra.dll'])).rejects.toThrow(/expected/)
    expect(leftovers()).toEqual([])
  })
  it('a host that names another version is refused', async () => {
    await expect(run({ probe: goodProbe({ version: '0.9.0' }) })).rejects.toThrow(/harness-pty reports version 0.9.0/)
    expect(leftovers()).toEqual([])
  })
  it('a protocol this CLI does not support is refused when it is below, and paired when it is above', async () => {
    // Supported: installed on its own, with any CLI build.
    const supported = await run({})
    expect(supported.paired).toBe(false)
    rmSync(supported.staging, { recursive: true, force: true })
    // Above: a host for a CLI build that needs it (spec §5, the pairing rule), canaried like any other and installed
    // only in that build's handover.
    const above = await run({ probe: goodProbe({ protocol: PTY_PROTOCOL + 1 }) })
    expect(above).toMatchObject({ version: '0.11.0', protocol: PTY_PROTOCOL + 1, paired: true })
    expect(readdirSync(above.staging).sort()).toEqual([...PTY_PAYLOAD_FILES].sort())
    rmSync(above.staging, { recursive: true, force: true })
    await expect(run({ probe: goodProbe({ protocol: PTY_PROTOCOL + 1 }, { version: '0.9.0' }) })).rejects.toThrow(/harness-serial reports version 0.9.0/)
    await expect(run({ probe: goodProbe({ protocol: PTY_PROTOCOL + 1, features: 'seed' }) })).rejects.toThrow(/features/)
    // Below every supported one, or not a protocol: no CLI will ever need it.
    await expect(run({ probe: goodProbe({ protocol: 0 }) })).rejects.toThrow(/protocol 0/)
    await expect(run({ probe: goodProbe({ protocol: 2.5 }) })).rejects.toThrow(/protocol 2.5/)
    expect(leftovers()).toEqual([])
  })
  it('a serial binary that names another version is refused', async () => {
    await expect(run({ probe: goodProbe({}, { version: '0.9.0' }) })).rejects.toThrow(/harness-serial reports version 0.9.0/)
    expect(leftovers()).toEqual([])
  })
  it('a canary that hangs past 5 s is refused', async () => {
    // Only the timers are faked: unzip is a real process and needs real time to finish.
    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
    let started = false
    const p = run({ probe: () => { started = true; return new Promise(() => {}) } })
    const assertion = expect(p).rejects.toThrow(/no answer within 5000 ms/)
    while (!started) await new Promise((r) => setImmediate(r))
    await vi.advanceTimersByTimeAsync(5_000)
    await assertion
    expect(leftovers()).toEqual([])
  })
})

describe('preparePtyPayload failure kinds', () => {
  it('a network error from the download is rethrown as it is, leaving no staging', async () => {
    const boom = new Error('ECONNRESET')
    const err = await run({ download: async () => { throw boom } }).catch((e) => e)
    expect(err).toBe(boom)
    expect(err).not.toBeInstanceOf(PtyPayloadRefused)
    expect(leftovers()).toEqual([])
  })
  it('an unzip that fails is no refusal: it carries the verified bytes, which a later prepare unpacks without a download', async () => {
    const zip = zipOf(PTY_PAYLOAD_FILES)
    let downloads = 0
    const err = await run({ download: async () => { downloads++; return zip }, unzip: async () => { throw new Error('spawn unzip ENOENT') } }).catch((e) => e)
    expect(err).toBeInstanceOf(PtyPayloadUnpackFailed)
    expect(err).not.toBeInstanceOf(PtyPayloadRefused)
    expect(err.reason).toBe('spawn unzip ENOENT')
    expect(err.zip).toBe(zip)
    expect(leftovers()).toEqual([])
    const again = await preparePtyPayload(entry, tmp + '/rt', { download: async () => { downloads++; return zip }, probe: goodProbe(), serve: async () => {} }, err.zip)
    expect(downloads).toBe(1)
    expect(readdirSync(again.staging).sort()).toEqual([...PTY_PAYLOAD_FILES].sort())
  })
  it('a probe that rejects is a refusal', async () => {
    await expect(run({ probe: async () => { throw new Error('exit 1') } })).rejects.toBeInstanceOf(PtyPayloadRefused)
    expect(leftovers()).toEqual([])
  })
})

describe('the serve canary', () => {
  it('runs after the version checks, on the staged host with its protocol and version, and its failure is a refusal', async () => {
    const asked: Array<{ binary: string; protocol: number; version: string }> = []
    const p = await run({ serve: async (binary, host) => { asked.push({ binary, ...host }) } })
    expect(asked).toEqual([{ binary: join(p.staging, 'harness-pty.exe'), protocol: 2, version: '0.11.0' }])
    rmSync(p.staging, { recursive: true, force: true })
    // Not reached for a payload a version check refused.
    asked.length = 0
    await expect(run({ probe: goodProbe({}, { version: '0.9.0' }), serve: async (binary, host) => { asked.push({ binary, ...host }) } })).rejects.toThrow(/harness-serial/)
    expect(asked).toEqual([])
    const err = await run({ serve: async () => { throw new Error('its create failed (spawn_failed: conpty.dll not found)') } }).catch((e) => e)
    expect(err).toBeInstanceOf(PtyPayloadRefused)
    expect(err.reason).toBe('harness-pty serve failed: its create failed (spawn_failed: conpty.dll not found)')
    expect(leftovers()).toEqual([])
  })

  it('a serve canary that never ends is refused at its bound', async () => {
    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
    let started = false
    const p = run({ serve: () => { started = true; return new Promise(() => {}) } })
    const assertion = expect(p).rejects.toThrow(/harness-pty serve failed: no answer within/)
    while (!started) await new Promise((r) => setImmediate(r))
    await vi.advanceTimersByTimeAsync(SERVE_CANARY_BOUND_MS)
    await assertion
    expect(leftovers()).toEqual([])
    // Cleanup included, under the updater's 30 s heartbeat timeout (harnessd/services.ts).
    expect(SERVE_CANARY_BOUND_MS).toBeLessThanOrEqual(20_000)
  })
})

describe.skipIf(process.platform === 'win32')('serveCanary, against stand-in binaries', () => {
  function script(name: string, body: string): string {
    const file = join(tmp, name)
    writeFileSync(file, `#!/bin/sh\n${body}\n`)
    chmodSync(file, 0o755)
    return file
  }
  const canaryHomes = (dir: string) => readdirSync(dir).filter((n) => n.startsWith('harness-pty-canary-'))

  it('a host that exits before it publishes is a failure, and its temporary home is gone', async () => {
    const homes = join(tmp, 'homes'); mkdirSync(homes)
    await expect(serveCanary(script('exits', 'exit 3'), { protocol: 2, version: '0.11.0' }, { tmpRoot: homes }))
      .rejects.toThrow(/exited with code 3 before it published its discovery file/)
    expect(canaryHomes(homes)).toEqual([])
  })

  it('a host that hangs is killed at the bound, and its temporary home is gone', async () => {
    const homes = join(tmp, 'homes'); mkdirSync(homes)
    const pidFile = join(tmp, 'pid')
    const binary = script('hangs', `echo $$ > '${pidFile}'\nexec sleep 30`)
    await expect(serveCanary(binary, { protocol: 2, version: '0.11.0' }, { tmpRoot: homes, timeoutMs: 3_000 })).rejects.toThrow(/no answer within 3000 ms/)
    const pid = Number(readFileSync(pidFile, 'utf8'))
    expect(() => process.kill(pid, 0)).toThrow()
    expect(canaryHomes(homes)).toEqual([])
  })

  it('runs the host outside its home, so a host or pane that lingers does not hold the folder', async () => {
    const homes = join(tmp, 'homes'); mkdirSync(homes)
    const cwdFile = join(tmp, 'cwd')
    await expect(serveCanary(script('cwd', `pwd -P > '${cwdFile}'\nexit 3`), { protocol: 2, version: '0.11.0' }, { tmpRoot: homes })).rejects.toThrow(/code 3/)
    expect(readFileSync(cwdFile, 'utf8').trim()).toBe(realpathSync(homes))
  })

  it('a home it cannot remove is left, and swept once stale, never while fresh', async () => {
    const homes = join(tmp, 'homes'); mkdirSync(homes)
    await expect(serveCanary(script('exits', 'exit 3'), { protocol: 2, version: '0.11.0' }, {
      tmpRoot: homes, remove: () => { throw Object.assign(new Error('EBUSY: resource busy or locked'), { code: 'EBUSY' }) },
    })).rejects.toThrow(/exited with code 3/)
    const left = canaryHomes(homes)
    expect(left).toHaveLength(1)
    // A canary may be running in a fresh one.
    expect(sweepCanaryHomes(homes)).toBe(0)
    expect(canaryHomes(homes)).toEqual(left)
    // Other folders are never touched.
    mkdirSync(join(homes, 'something-else'))
    expect(sweepCanaryHomes(homes, CANARY_HOME_STALE_MS, Date.now() + CANARY_HOME_STALE_MS + 1_000)).toBe(1)
    expect(readdirSync(homes)).toEqual(['something-else'])
    expect(sweepCanaryHomes(join(tmp, 'no-such-folder'))).toBe(0)
  })
})

// The real host (`cd pty && cargo build`, then HARNESS_PTY_BIN=<that harness-pty>): start, hello, one pane that exits, shutdown.
const realHost = process.env.HARNESS_PTY_BIN
describe.runIf(realHost)('serveCanary, against the real host', () => {
  // Short off Windows: the host's Unix socket is in its home, and a macOS temporary folder is half a socket path already.
  let homes: string
  beforeEach(() => { homes = mkdtempSync(process.platform === 'win32' ? join(tmpdir(), 'hpc-') : '/tmp/hpc-') })
  afterEach(() => { rmSync(homes, { recursive: true, force: true }) })

  // Windows: the host's console process (OpenConsole.exe) must not outlive the canary, or the folder it started in
  // cannot be removed (and, staged, cannot be renamed). A leftover is named in the message.
  async function expectNoneLeft(): Promise<void> {
    if (process.platform !== 'win32') return
    const left = await processesInFolder(realHost!)
    expect(left, `processes still running from ${realHost}: ${JSON.stringify(left)}`).toEqual([])
    rmSync(homes, { recursive: true, maxRetries: 0 })
  }

  it('passes, and leaves no host and no home behind', async () => {
    const said = await probeVersionLine(realHost!) as { version: string; protocol: number }
    await serveCanary(realHost!, { protocol: said.protocol, version: said.version }, { tmpRoot: homes })
    expect(readdirSync(homes)).toEqual([])
    await expectNoneLeft()
  }, 30_000)

  it('a host that cannot start a pane fails it', async () => {
    const said = await probeVersionLine(realHost!) as { version: string; protocol: number }
    await expect(serveCanary(realHost!, { protocol: said.protocol, version: said.version }, { tmpRoot: homes, command: [join(tmp, 'no-such-shell')] }))
      .rejects.toThrow(/its create failed|its pane exited with/)
    expect(readdirSync(homes)).toEqual([])
    await expectNoneLeft()
  }, 30_000)
})

describe('probeVersionLine', () => {
  // The same `<bin> version` run as ptyHost/launch.ts binaryVersion's (one implementation, 5 s, hidden).
  it.skipIf(process.platform === 'win32')('parses the last line a binary prints, and rejects one that fails', async () => {
    const good = join(tmp, 'good')
    writeFileSync(good, '#!/bin/sh\necho "starting"\necho \'{"version":"0.11.0"}\'\n', { mode: 0o755 })
    await expect(probeVersionLine(good)).resolves.toEqual({ version: '0.11.0' })
    const bad = join(tmp, 'bad')
    writeFileSync(bad, '#!/bin/sh\nexit 3\n', { mode: 0o755 })
    await expect(probeVersionLine(bad)).rejects.toThrow()
  })

  // A binary whose child holds its output open: a synchronous run outlived its timeout with it, and the updater's event
  // loop with it. The default canary refuses it within 5 s, and the loop runs meanwhile.
  it.skipIf(process.platform === 'win32')('a default probe that never answers is refused within the timeout, the event loop running', async () => {
    const unzip = async (_zip: Buffer, dest: string) => {
      for (const name of PTY_PAYLOAD_FILES) if (name !== 'harness-pty.exe') writeFileSync(join(dest, name), name)
      // Its child keeps stdout open after the shell is killed at the timeout.
      writeFileSync(join(dest, 'harness-pty.exe'), '#!/bin/sh\n(sleep 8)\n', { mode: 0o755 })
    }
    let beats = 0
    const beat = setInterval(() => { beats++ }, 100)
    const started = Date.now()
    try {
      const err = await preparePtyPayload(entry, join(tmp, 'rt'), { download: async () => Buffer.from('zip'), unzip }).catch((e) => e)
      expect(err).toBeInstanceOf(PtyPayloadRefused)
      expect((err as PtyPayloadRefused).reason).toMatch(/no answer within 5000 ms/)
      expect(Date.now() - started).toBeLessThan(7_000)
      expect(beats).toBeGreaterThan(20)
    } finally { clearInterval(beat) }
    expect(leftovers()).toEqual([])
  }, 15_000)
})

describe('sweepStagingFolders', () => {
  it('removes stale staging folders and nothing else', () => {
    const root = join(tmp, 'rt', 'pty')
    mkdirSync(join(root, '.staging-1-2'), { recursive: true })
    mkdirSync(join(root, '.staging-3-4'), { recursive: true })
    mkdirSync(join(root, '0.10.0'), { recursive: true })
    expect(sweepStagingFolders(join(tmp, 'rt'))).toBe(2)
    expect(readdirSync(root)).toEqual(['0.10.0'])
    expect(sweepStagingFolders(join(tmp, 'nothing'))).toBe(0)
  })
})

describe('fetchPtyEntry', () => {
  const good = { version: '0.11.0', url: 'https://cdn.example/p.zip', sha256: 'b'.repeat(64), size: 10 }
  const serve = (body: string, status = 200) => vi.stubGlobal('fetch', async () => new Response(body, { status }))
  const manifest = (e: object) => JSON.stringify({ pty: { 'win32-x64': e, 'win32-arm64': { ...good, version: '0.12.0' } } })
  afterEach(() => vi.unstubAllGlobals())

  it('reads the entry of the platform from the published shape', async () => {
    serve(manifest(good))
    expect(await fetchPtyEntry('https://m.example/pty/metadata.json', 'win32-x64')).toEqual(good)
    expect((await fetchPtyEntry('https://m.example/pty/metadata.json', 'win32-arm64'))?.version).toBe('0.12.0')
  })
  it('an absent platform is null', async () => {
    serve(JSON.stringify({ pty: { 'win32-arm64': good } }))
    expect(await fetchPtyEntry('https://m.example/m.json', 'win32-x64')).toBeNull()
  })
  it('a top-level entry (not the published shape) is null', async () => {
    serve(JSON.stringify({ 'win32-x64': good }))
    expect(await fetchPtyEntry('https://m.example/m.json', 'win32-x64')).toBeNull()
  })
  it.each([
    ['an http url', { url: 'http://cdn.example/p.zip' }],
    ['a 63-char sha', { sha256: 'b'.repeat(63) }],
    ['a non-hex sha', { sha256: 'z'.repeat(64) }],
    ['size 0', { size: 0 }],
    ['size 1.5', { size: 1.5 }],
    ['size "10"', { size: '10' }],
  ])('%s is null', async (_n, bad) => {
    serve(manifest({ ...good, ...bad }))
    expect(await fetchPtyEntry('https://m.example/m.json', 'win32-x64')).toBeNull()
  })
  it('a non-2xx response is null', async () => {
    serve(manifest(good), 404)
    expect(await fetchPtyEntry('https://m.example/m.json', 'win32-x64')).toBeNull()
  })
  it('malformed JSON is null', async () => {
    serve('{nope')
    expect(await fetchPtyEntry('https://m.example/m.json', 'win32-x64')).toBeNull()
  })
})